The method used as of OpenSocial 0.9 to push an update to a user’s activity stream is osapi.activities.create(...). This method allows a developer to quickly output a message from an application to an activity stream or any available activity consumption channel provided by the container.

The osapi.activities.create(...) method accepts one parameter, a JSON object containing the activity request parameters listed in Table 6-1.

Using the parameters listed in Table 6-1 as a base, we can build a JavaScript block to enable us to push out an update to the user’s activity stream:

//insert new activity for the current viewer
osapi.activities.create({
  userId: "@viewer",
  groupId: "@self",
  activity: {
   title: "My application does all sorts of cool things",
   body: "<a href='http://www.mysite.com'>Click here</a> for more information",
   url: "http://www.mysite.com/"
  }
}).execute();

To generate the update, we make a request to osapi.activities.create(...) with our JSON object as the parameter. In the update, we specify that the activity stream to which the update should be pushed is that of the current application viewer, and the group to push to is self; then, we define an activity object to specify the content. Within our activity object, we include a title, the URL that the title will link to, and the description (body) of the update. The body of an activity accepts a small subset of HTML tags, including <b>, <i>, <a>, and <span>. Executing this code will push an update to the user’s activity stream.

When pushing out an activity for a user, you need to ensure that application activities can be posted on the user’s behalf, even if she has not explicitly granted the application permission to do so. This is where the activity priority comes into play.

You can include an optional flag, priority, in an activity push to set the activity’s priority. This is a Boolean field that contains a value of 0 (low priority) or 1 (high priority). The value depends on whether the user who is about to push an activity has granted your application permission to do so, and on the container implementation. If you define a high priority (1) and the user has not granted your application permission to push out activities on her behalf, the application will attempt to load an authentication flow to prompt her to allow the activity. If you set a low priority (0) and the user has not granted your application permission, the update is ignored and no authentication flow will be presented to provide her the option to permit the update to her activity stream.

You can set an activity with a priority flag simply by placing the value in the JSON object passed to the push request:

//insert new activity for the current viewer with a high priority
osapi.activities.create({
   userId: "@viewer",
   activity: {
      title: "Get more information on my blog",
      url: "http://www.nakedtechnologist.com/",
      priority: 1
   }
}).execute();

The preceding example requests the user’s permission to push out the activity if she has not already granted the application permission to do so. This may come up if a user has not allowed the application access to her social data, or if she is viewing the application in a preview state.

Adding visual media to an activity that will be displayed to other users will promote richer degrees of interaction with its content, capture user attention more so than standard text and links, and ultimately increase the number of people viewing and installing your application.

An activity push request includes an optional field for mediaItems, through which the developer can embed images, audio, or video into the activity’s content.

The method available for creating a media item within OpenSocial is opensocial.newMediaItem(...), which accepts a MIME type defining the media and a URL to the media item itself, such as an image:

//create a new media item for an image
var imageUrl = "http://www.mysite.com/image.jpg";
var mediaImg = opensocial.newMediaItem("image/jpeg", imageUrl);
var mediaObj = [mediaImg];

//build parameter list for the activity
var params = {};
params[opensocial.Activity.Field.TITLE] = "Posting my image";
params[opensocial.Activity.Field.URL] = "http://www.myserver.com/index.php";
params[opensocial.Activity.Field.BODY] = "Testing <b>1 2 3</b>";
params[opensocial.Activity.Field.MEDIA_ITEMS] = mediaObj;
var activityObj = opensocial.newActivity(params);

//make request to create a new activity
osapi.activities.create({
   userId: "@viewer",
   activity: activityObj
}).execute();

The process of including a media object in the preceding example comprises three steps. The first task is to create a new media item object, making a request to opensocial.newMediaItem(...) to create the structure. The first parameter specified, image/jpeg, is the MIME type denoting what type of data we are creating. The second parameter is the string specifying the URL to our image. As is typical when embedding media into an activity, we then create an array out of that object.

The second step is to create our activity object to house all of our activity’s data, including the media object. The activity parameters can be specified as a JSON object or by calling the opensocial.newActivity(...) method to generate the required structure. We create entries for the title, body, and URL as the base text data to populate the activity. We then add the media item via the opensocial.Activity.Field.MEDIA_ITEMS entry, inputting the array containing the media object we created in the previous step. Next, we call the opensocial.newActivity(...) method to generate the activity structure.

In the final step, we make a request to create the activity. We pass in the userId of the user we would like the activity to be posted for—in this case, the current viewer—and then insert our activity based on the object we created earlier.

These steps will post out an activity containing an image. You can follow the same process to insert a video or audio stream—just keep in mind that you’ll have to set the URL and a correct MIME type for the data being presented.