Home ›

AIM Module Plugin Tutorial

This tutorial demonstrates how to write a simple AIM Module Plugin using the AIM 6.8 Client and optionally, Visual Studio.Net 2003 to edit and debug the plugins.

Prior to starting this tutorial, make sure to install and run AIM 6.8 available on http://www.aim.com.




Lesson 1: Creating an AIM Module Plugin

You will need a compression application like WinZip in order to create an AIM Module Plugin. Use a sample AIM Module Plugin as a template to build your own plugin. You can get it from here.

Rename the HelloAMO.amo to HelloAMO.zip, it is really just a zipfile with a renamed extension. Open it using WinZip. This sample Module Plugin contains the following files when you open it in WinZip:

  • plugin.xml
  • plugin.htm
  • plugin1.png
  • settings.htm
  • about.htm

Extract the above files into a working directory.

Open the plugin.xml in a text editor. It looks like the below, and provides you a starting point for your own Module Plugin. Please refer to the API document for a detailed explanation on the following XML file format.

<?xml version="1.0" encoding="utf-8"?> <plugin 
   schema     = "1"
   type       = "html"
   uuid       = "{DEV_KEY_GOES_HERE}"
   name       = "Test Module Plugin"
   version    = "1.0.0.1"
   description= "A simple test Module Plugin"
   vendor     = "Author of plugin"
   url        = "http://gallery.aim.com/{6A773144-4967-3356-516B-546C30525655}"
   vendorUrl  = "http://gallery.aim.com"
   iconUrl    = "plugin1.png"
   smallIconUrl = "plugin1.png">
 <param name="pluginUrl" value="plugin.htm"/>
 <param name="pluginSns" value="false"/>
 <param name="settingsUrl" value="settings.htm"/>
 <param name="aboutUrl" value="about.htm"/>
 <param name="aboutFixedSize" value="200,150"/>
 <param name="requiresSession" value="true"/>
 <param name="requiresDom" value="true"/>
</plugin>




Lesson 2: Registering an AIM Plugin Developer key

To make your new object available and identified uniquely on the AIM servers, you will need to get a free developer key from the Open AIM website here. Just use your AIM screen name to sign in and get a plugin key.

Setting your AIM Developer Plugin Key

In the plugin.xml above, you will see a line that looks like this: 

uuid = "{DEV_KEY_GOES_HERE}"

Replace the “DEV_KEY_GOES_HERE” text above with the key you obtained at http://open.aim.com, retain the curly braces.

IMPORTANT: : In order for your own AMO to be unique and recognized by the AIM servers, you must obtain the key which will be in the format of a UUID. For more info on UUIDs click here.

We recommend that you hash or fingerprint your Module Plugin, but we recommend you do so on the AIM Development site ONLY after it is stable and ready for deployment. For more information on fingerprinting and how to create a fingerprint visit the “Keys and Fingerprint” FAQ here.




Lesson 3: Developing your Module Plugin

The Module Plugin API has full access to the Open AIM API, this is the same API used to build AIM 6.8 as well as plugins or bots. You have a tremendous amount of flexibility and control available to you.

Modify plugin.xml to add the parameters that you need for your Module Plugin.

Create an icon and an image to identify your Module Plugin in the client and the gallery respectively.

Zip the contents back into a zipfile and when you are ready to test it within the AIM client, rename the extension to .amo. To test your Module Plugin, simply doubleclick it and it will auto launch AIM 6.8 is it is not already launched, which will install your Module Plugin. You can see it in the module area which looks like the below… (AOL Radio is shown open in this example)



Functionality available
Here are some of the things you can do and the samples show you how to do them...
  • Add a command to the AIM 6.8 menus, for instance the Actions menu, and snag the command event in the Module Plugin to react to the menu.
  • Add custom Settings and About for your Module Plugin.
  • Launch an authenticated URL seamlessly using SNS. The authenticated URL can be launched either in an external browser or within an Module Plugin window.
  • You can use DAccEvents, the link to their documentation is here. DAccEvents are Open AIM events sent to the AIM 6.8 client, and the client will forward all or some of them to the Module Plugin on demand. For instance, you can snag and do custom stuff when you get an OnImReceived or OnUserChange.
  • Keep your Module Plugin running in the background when it is closed. This is how AOL Radio, one of our default Module Plugins work, it continues to play even if you navigate away from it.
  • Retrieve the primary user’s buddy list and the primary and linked identities.
  • Do Actions like pop a toast, find and open Windows, Open Conversation.
  • Get and set preferences.
  • Send HTTP requests and get the response.
And much more.

Refer to the Module Plugin FAQ
To get a general idea as to the kinds of questions and issues you may run into, see the FAQ.

Refer to the Module Plugin API Document
The Module Plugin API Document should help you get an idea as to the different kinds of functionality we offer your Module Plugin.

Refer to the samples
We provide a wide range of samples that demonstrate the Module Plugin API usage here. The samples demonstrate how to accomplish many common actions with the API, such as accessing the Buddy List, sending and receiving IMs, and setting profiles and away messages.





Lesson 4: Deploying your finished Module Plugin

Your Module Plugin is ready for use and is fully tested and conforms to our security recommendations. Ensure that your Module Plugin is free of script errors and does nothing that can destabilize the AIM 6.8 client.

Fingerprint your Module Plugin

The next step is to fingerprint your Module Plugin on the http://developer.aim.com/manageKeys.jsp site. This adds a level of security to your Module Plugin, no one can reuse your UUID.

Upload your Module Plugin to the gallery

Go to http://gallery.aim.com/browse/plugins and on the right, sign in as the same Screenname that you used to create the UUID for your Plugin. There is an Upload Now option, select it. On that page, select "Plugin" as Application Type.

Enter the name of your Module Plugin and a description. We recommend that you specify that your Module Plugin only supports AIM 6.8 and higher versions.

Add a screenshot and your plugin icon that you want to have your Module Plugin identified with.

For the UUID, you need to paste your UUID you obtained in lesson 2 from the plugin.xml without the braces.

Press submit and you are ready to go. Keep in mind, the Module Plugin needs to be approved by the AIM Plugin approval team, and when that is complete, you will see your Module Plugin on the Gallery :)



Congratulations, you just built and deployed your first AIM Module Plugin!!!




Appendix A: List of samples

You can refer to the samples we have provided for you to add functionality to your Module Plugin here.

» Submitted by Developer Network on June 9, 2008 - 2:24pm.