Activity Extender API
LiveBot features an Extended version of the Messenger Activity API. The main extension will be the support of more than 2 users in your activity. The API is based on the original API, so make sure you’ve read and understand the original documentation. Here I’ll explain the basics you need to know to create your own ‘extended activity’.
Basics
Include the script http://livebot.msgweb.nl/_api/extended_activities.js in the head section of your activity. Call ActivityExtender.Initialize() just before ext.Channel.Initialize().
It’s not recommended to use any of the API calls before Channel_OnRemoteAppsLoaded has been called.
Instead of window.external, always use ‘ext’.
Reference
CHANNEL OBJECT
New events:
- Channel_OnRemoteAppsLoaded()
The ext.Users object has been updated with the information of all participating users. It will only be triggered when the client user just entered the activity.
Edited events:
- Channel_OnRemoteAppLoaded(Object user)
A new user has joined the activity. ‘user’ is the user object of the new user. - Channel_RemoteAppClosed(Object user)
A user left the activity. ‘user’ is the user object of the user. Note that ext.Users doesn’t contain this user anymore (its value will be null).
Edited functions:
- Channel.SendData(String data)
Send data to all users. - Channel.SendData(String data, Number uid)
Send data only to the user with identifier uid. - Channel.SendData(String data, Object userObject)
Send data only to the user userObject.
New properties:
- Channel.DataUser
Contains the user object who sent the latest data.
USERS OBJECT
New functions:
- Users.CountActive()
Returns the number of users who are still in the session. When someone leaves the activity, this value will be updated, but ext.Users.Count won’t be.
USER OBJECT
New properties:
- User.id
The identifier of the user. Users.Item(myUser.id) will return myUser.
Testing
To test your own ‘extended activity’, create a msgrp2p.xml file in your Messenger directory, as described in the original API documentation. Then, say ‘activity’ to the bot. When it says ‘What application do you want me to start?’ don’t choose one of the options, but just type ‘test activity http://url-of-your-activity’ instead.
The activity extender comes with a debugging module. Simply call ActivityExtender.Initialize(true) instead of calling the function without any parameters. You can now call ActivityExtender.debug(message), to add a debug message.
Example
Take a look at the source of the Memory game!
1 comment August 15th, 2006