">mixi Developer Center (mDC)

mixi Apps

mixi Apps (English) » Technical Specification (new method) » PC » Send Activities

Send Activities

In the mixi App, communication with Friends is critically important. Users are curious how their Friends enjoy mixi Apps, Knowing Friends activities through the communication greatly motivates the users to use mixi Apps repeatedly.

In OpenSocial, updated information regarding the user’s activities is called “Activity (or Activities).” In the mixi App specification, we evaluate the Activities most important among all APIs. The OpenSocial JavaScript APIs prescribes functionality for creating and publishing Activity from an OpenSocial application. The mixi App specification enables the developer to publish Activity with images that can catch more attention from Friends.

activity.PNG
(Image size is H 76px W 76px.)

The created Activity is published in the feed list on the user’s profile page as well as on pages of Friends of the user. This documents covers following items regarding the Activity:

  1. Preparing for Activity API
  2. Activity types
  3. Sending Activities
  4. Creating Activities to Specified Recipients
  5. Publishing Range of Activities
  6. Specifying landing page from Activities
  7. Error Codes

Preparing for Activity API

You need to previously prepare for using the Activity API.

Actyvity types

The available activity for a new method mixi app is only the communication feed.

Type Condition Displayed page
Communication Feed Posted only if the user explicitly permits the posting home.pl
new_appli.pl
list_appli_activity.pl

When the API is called to post the communication feed, it is not directly posted but the pop-up window is displayed to make sure if the user permits the posting. The communication feed is posted only if the user permits posting. As a result, the posted communication feed is displayed on friend’s home.pl. 

Sending Activities

Activities through OpenSocial JavaScript APIs are sent by following procedure.

  • Create an opensocial.Activity object containing activity information.
  • Request a server to create Activity by the opensocial.requestCreateActivity() .

Creating Activities with images requires to generate opensocial.MediaItem objects before generating Activity objects.

Generating opensocial.Activity Object

First of all, an opensocial.Activity object is created to create and publish the Activity. This Activity object holds specific activity information. In a sample code below, a simple Activity object handing only text information is created. The text information is described in the opensocial.Activity.Field.TITLE.

var params = {};
params[opensocial.Activity.Field.TITLE] = "Hello!";
var activity = opensocial.newActivity(params);

The specified activity strings are only valid up to 255 characters. Please note that figures after 256th characters are omitted. In addition, in the case that an Activity handles text and image information, an opensocial.MediaItem object should be created. The sample code below illustrates an example of creating an Activity with text and image. The MediaItem object can be generated using the opensocial.newMediaItem() and the MIME Type, a URL of the image and a parameter indicating the image should be specified here.

var mediaItem = opensocial.newMediaItem("image/gif", "http://your.server.host/image.gif");
var ap = {};
ap[opensocial.Activity.Field.TITLE] = "Hello!";
ap[opensocial.Activity.Field.MEDIA_ITEMS] = [mediaItem];
var activity = opensocial.newActivity(ap);

A MediaItem object can be specified in an array as the opensocial.Activity.Field.MEDIA_ITEMS field. The mixi App specification enables the developer to specify up to 3 MediaItem objects in the array.

The size of the image as a MediaItem object should be H 76px and W 76px. In the case the size is a different from the specified one, the image is displayed with the size of 76 × 76. (Animated GIF is not permitted)

Requesting a Server to Create and Publish Activities

Nothing is happened by only creating the Activity object. It is necessary to request a server to generate the Activity by the opensocial.requestCreateActivity(). The sample code below shows an example of requesting a server to create and publish the Activity created as the Activity object.

var activity = ...;
opensocial.requestCreateActivity(
        activity, opensocial.CreateActivityPriority.HIGH, function(response) {
  if (response.hadError()) {
    var code = response.getErrorCode();
    // do something...
  } else {
    // do something...
  }
});

The Activity object created is specified as the first parameter of the requestCreateActivity(). For the second parameter, priority of creating the Activity can be specified in OpenSocial. In the current mixi App specification, however, this priority parameter is not supported and it is ok to specify opensocial.CreateActivityPriority.HIGH.

For the third parameter, the callback function, which is called after the completion of the Activity publication, is specified. An opensocial.ResponseItem object is specified as the callback function parameter. The developer should check the result of the hadError() to confirm whether the creating and publishing the activity was created and published successfully or not.

Creating Activities to Specified Recipients

When creating an Activity from a mixi App, up to 2 users related to the Activity can be specified as recipients, which is called “creation of activities with specified recipients” by mixi.ActivityField.RECIPIENTS.

var user1 = ...; // 関係者その1のID
var user2 = ...; // 関係者その2のID
var params = {};
params[opensocial.Activity.Field.TITLE] = "Hello!";
params[mixi.ActivityField.RECIPIENTS] = [user1, user2];
var activity = opensocial.newActivity(params);

Thus the created Activity is associated with users specified as user1 and user2. 

Publishing Range of Activities

The status of the mixi App determines if an Activity sent as a result of user A’s Friend using mixi Apps can be published on the user A’s page. Specifically, it is determined as shown in the table below.

  User A owns the application User A does not own the application
Application under development Published Not published
Launched application Published Published

Specifying landing page from Activities

In the mixi App specification, the developer is able to set up a link from the Activity by the opensocial.Activity.Field.URL. Without specifying the link, the Activity is linked to the application page (run_appli.pl) which Owner ID is specified from the user when the Activity is sent. Besides, the developer can customize the link as follows:

  • Landing page – run_appli.pl or view_appli.pl (application description page)
  • Parameter to be specified at launching the mixi App – appParams

Specifying different parameters for each Activity enables to provide different user experience based on the parameter when the user runs the mixi App.

var appId = ...; // アプリID
var data = {};
data[opensocial.Activity.Field.TITLE] = ...;
data[opensocial.Activity.Field.URL] = "http://mixi.jp/run_appli.pl?id=" + appId + "&appParams=%7B%22uid%22%3A%221569%22%7D";
var activity = opensocial.newActivity(data);
opensocial.requestCreateActivity(
    activity,
    opensocial.CreateActivityPriority.HIGH,
    function(res) {...}
);

appParams is JSON with URL encording. The parameter specified by appParams is given as the parameter to the start URL when the user click the activity feed and run the app.

In the case of specifying the application description page (view_appli.pl) as the landing page rather than the applications page, “run_appli.pl” can be replaced by “view_appli.pl” in the URL parameter.

URL cannot be other than http://mixi.jp/, pages other than view_appli.pl or run_appli.pl, or a different application ID.

You can specify the activity's destination URL for a user who access with a mobile device on the mixi.ActivityField.MOBILE_URL field. The available URL is the same as モバイル版「コミュニケーションフィードの投稿方法」 parameter mobileUrl. Following codes are the sample.

var data = {};
data[opensocial.Activity.Field.TITLE] = "Hello Activity";
data[mixi.ActivityField.MOBILE_URL] = "http://ma.mixi.net/1234/?url=http%3A%2F%2Fexample.com%2Ffoo";
var activity = opensocial.newActivity(data); 

Error Codes

In calling Activities API, some error codes may be available. By getErrorCode() in ResponseItem object, the developer is able to obtain these error codes. Analyzing these codes, the developer can determine what causes these errors and how to handle them.

Error code Occurrence condition
400 (BAD_REQUEST) Specifying inappropriate MediaItem, more than 4 MediaItem, inappropriate recipient or URL, and no authentication, or No target ID is specified.
401 (UNAUTHORIZED) The permission of mixi_apps2 scope is not obtained from the user
403 (FORBIDDEN) No Authorization or a selector including @self or @sfriends is not specified
500 (INTERNAL_SERVER_ERROR) mixi internal error

 

TOP OF THIS PAGE