OpenSocial Activity Posting

NOTE: This code and post was written for an older version of Opensocial. I make no guarantees as to it's validity in later versions.

There are four APIs to opensocial: Javascript, Activities, People, and Persistence. The last three haven't been released yet, but the Javascript one already implements some of the features that they will support. For example. the People API will let you retrieve a specific person, or a specific person's friends. That can already be done (mostly, you can't get a person by ID yet) in the Javascript API. I ran through what could be done with people pretty quickly, and was able to get a demo up using persistence as well, but activities have been puzzling me.

The Activities Data API describes how you will be able to create, retrive, update, and delete activities. That sounds sweet. Except for the fact that right now, with the Javascript API, the only thing you can do is create activities. Even doing that is kind of confusing, so I'm going to go through what I've learned so far.

Before you can even think about creating an event, you have to create a stream. You do this with opensocial.newStream. The first parameter, folder, has apparently already been deprecated, so I've just been putting "null" for it. Title, the second parameter, is apparently the title of the stream (real big surprise.) I've done some tests, and if you use newStream with the title of an already existing stream, it still creates a new stream. I'm not sure what it does to the old stream, but activities that have already been posted to a person's update feed aren't removed. The tests were part of a demo app I'm working on, so they're not in their own test apps. Once I get them seperated, I'll post a link to them. Finally, you can post a map of optional parameters. Right now, the only two fields that interest me are USER_ID, and FAVICON_URL. I haven't tested FAVICON_URL yet, to see how well it works, but USER_ID got me really excited. When I was first working with the activities, I thought that I could only post updates to my own update feed (which is sort of redundant, but it is the default if no USER_ID is specified.) All you have to do is specify the USER_ID, and any activities posted to that stream will go on that user's update feed. SO, here's the line of code that I use to create my stream.


var activitystream = opensocial.newStream(null, title, { "USER_ID": friendId });
"title" is a variable containing whatever I want the stream to be titled. "friendId" contains the id of the friend whose feed the activities will be posted to.


Alright then, the stream is set up. Now you get to create the event. That's accomplished with opensocial.newActivity. It has three parameters as well. The first one, stream, is the stream variable you just set up. The second, title, is the most important. It is what will show up on the update feed. Also, since the optional parameters don't seem to be doing jack at the moment, it's ALL the person who recieves this activity will see. Here's how you set up the activity.


var activity = opensocial.newActivity(activitystream, text_to_display, null)

I just leave opt_params as null, since they're pretty useless now.


Almost done! You've set up the stream and the activity, and even told the activity what stream it's going to be posted to. Now, all you have to do is let it loose. This is done using the opensocial.requestCreateActivity method. It has, beleive it or not, THREE PARAMETERS. The first is the activty variable, which has the stream variable, which swallowed the fly...etc. The second is the "priority" of the posting. There are only two options (at least at the moment), opensocial.CreateActivityPriority.HIGH, and opensocial.CreateActivityPriority.LOW. HIGH means that if the stream you wrote to doesn't exist, the activity will still be posted. If you choose LOW, and the stream doesn't exist, the activity will not be posted. Supposedly, there is a chance that using HIGH will navigate away from the current page (your opensocial gadget,) but I've never had that happen to me, and I've only been using HIGH. The third parameter is a function to be called when the activity has been posted. It's optional, but I've been using it to verify that the operation completed. Here's the last line of code you need.


opensocial.requestCreateActivity(activity, opensocial.CreateActivityPriority.HIGH, callbackFunction);


There you have it, the longest explanation of three lines of code ever. ;-P At least now you can post updates to your friend's update feeds. One other little caveat I should mention, if the title of the activity is identical to another activity in the same stream, it will not be re-posted. My guess is that changing the opt_params might allow this to happen, but I haven't tested it yet.

As far as programmatically accessing streams/activities, I'm totally scoobied at the moment. After I post this, I'm going to check the DataRequest methods, and see how much I can/can't do with them, but for now, I'll leave you with being able to post activities. Catch youse later.