The MSG API is a way for you to be able to embed MSG presence icons within your webpages to display (for example) next to users names in forum postings etc.
In order to use the API at all, we first need to ensure that we can authenticate users correctly. For this we need to know that the BuddyXML service is configured to handle the cookie you may pass for authentication, currently only Moodle authentication is supported.
Once you know that the authentication methd you wish to use is correctly configured you can move on to actually using the API. The API is made up of a set of JavaScript files and a CSS stylesheet, you can either link to our copies of these files (recommended if you always want to link to the most recent versions), which can be found at: msg.open.ac.uk/MSGClientAPI/ (no longer available), or you can host the files on your own server, the files can be obtained from the MSGClientAPI module on our cvs server (no longer available).
Here is a step by step guide to embedding the presence icons on your page:
Step 1
Link to the JavaScript and CSS files in the head tag of your page using the following code:
<link rel='stylesheet' type="text/css" href="http://msg.open.ac.uk/MSGClientAPI/msgstyle.css" />
<script type="text/javascript" src="http://msg.open.ac.uk/MSGClientAPI/msgconfig.js" ></script>
<script type="text/javascript" src="http://msg.open.ac.uk/MSGClientAPI/jsr_class.js" ></script>
<script type="text/javascript" src="http://msg.open.ac.uk/MSGClientAPI/msgservice.js" ></script>
<script type="text/javascript" src="http://msg.open.ac.uk/MSGClientAPI/msgcommon.js" ></script>
If you are hosting the API files on your own server then remember to change these links to point to your copies of the files.
Step 2
Now we need to add some JavaScript to set up the icons when the page is first loaded. Add the following code into the ‘head’ tag:
<script type="text/javascript">
authArr = new Array();
authArr['resource'] = "Moodle";
authArr['username'] = "MoodleSession";
authArr['password'] = "checkthecookie";
authArr['MoodleSession'] = "b3bca1828fb5897fd0c9882678a57115";
authArr['MoodleSessionTest'] = "HkCe0SeH9D";
MSGAPIconf.imgroot = "http://pckm042.open.ac.uk:8080/MSGClientAPI/images/";
MSGAPIconf.msg_jabberurl = "http://msg.open.ac.uk/buddyxml";
MSGAPIconf.msg_host = "msg.open.ac.uk";
MSGAPIconf.msg_jabberui = "http://msg.open.ac.uk/msg";
initMSG(authArr,"3","Alex Little");
</script>
To roughly explain this code, the authArr sets up the parameters that will be passed to BuddyXML in order to authenticate the user. In this case we are passing the Moodle cookies of the current user, though obviously you wouldn’t write the actual cookie details into the html, this would be dynamic content, generated by your page.
This authArr is passed to the initMSG function, which has 3 parameters, the first parameter tells the API which authentication mechanism to use and the associated parameters required to log the current user in. The second and third parameters pass the current users Jabber Id and name respectively.
Next come a series of configuration settings (MSGAPIconf), so that you are pointing to the correct MSG server, the settings listed are just the ones you are required to set and there are other options available which you may like to change, for example to change the terminology of the presence states, or the text of the notification when a new message arrives. To find all the settings have a look at "function configAPI()" in msgconfig.js (no longer available)
Step 3
Now we add JavaScript code to display the presence icons for each user, or for the current user. To add the presence icon for the current user, this will nofity the user if they receive a new message and provide a link for them to go directly to the MSG client add the following code:
<span id="msg_widget">
<script type="text/javascript">displayMyStatus();</script>
</span>
This can be placed whereever you feel is most appropriate on the page. Then to add other users’ presence states, you would need to add the following code for each user you’d like to display:
<span id="presencenode_X">
<script type="text/javascript">displayUserStatus('X');</script>
</span>
You need to replace the ‘X’ with the Jabber Id of the user you would like to display. If you need to display the presence node for the same person multiple times, change the code listed above to:
<span id="presencenode_X_1">
<script type="text/javascript">displayUserStatus('X',1);</script>
</span>
For each instance of the user, increment the number appended to the id and the displayUserStatus parameter.
Step 4
Finally, you need to add a call to checkLogin() in the body onload attribute. This checks the current user is logged in to MSG, initialises the presences icons and displays the appropriate presence icon for each user. As an alternative to this you can add the following code after the final user presence icon is displayed:
<script type="text/javascript">
checkLogin();
</script>
And that should be all!! We have put together an example html page to demonstrate all the JavaScript described above in use.
Please let us know if you have any comments, queries or feedback on the API ๐