">mixi Developer Center (mDC)

mixi Apps

mixi Apps (English) » Technical Specification » PC » Let's use the Request API

Let's use the Request API

Using the Request API, users are able to send a request to friends, such as “Please receive the bunch of flowers.”

  1. Preparation for the Request API
  2. Sending Request
  3. Sent User and obtained Request ID
  4. Deleting the sent request

Preparation for the Request API

You need to previously prepare for using the Request API.

Sending the request

Use the opensocial.requestShareApp() function to use the Request API from the mixi app. Calling the function, a request can be sent to friends. This requestShareAPP function is the same as the function for sending an invitation.

var idSpecParams = {};
idSpecParams[opensocial.IdSpec.Field.USER_ID] = ["user_id1", "user_id2", ...];
var recipients = opensocial.newIdSpec(idSpecParams);
var reqParams = {};
var image = opensocial.newMediaItem("image/gif", "http://server.name/image.gif");
reqParams[mixi.Request.Field.IMAGE] = image;
reqParams[mixi.Request.Field.FILTER_TYPE] = mixi.Request.FilterType.JOINED_ONLY;
reqParams[mixi.Request.Field.URL] = "http://mixi.jp/run_appli.pl?id=[アプリID]&appParams=...";
reqParams[mixi.Request.Field.MOBILE_URL] = "http://ma.mixi.net/[アプリID]/?url=...";
reqParams[mixi.Request.Field.BODY] = "花束を贈りますので受け取ってください";
opensocial.requestShareApp(recipients, null, function(response) {...}, reqParams);

The argument for the requestShareApp() function is as shown below.

  • The 1st argument specifies the “VIEWER_FRIENDS” or open social.IdSpec object.
  • The 2nd argument specifies the default initial script. When null is specified, the strings specified in the mixi.Request.Field.BODY are used.
  • The 3rd argument specifies the callback function called after sending a request.
  • The 4th argument specifies the object that has the content to send as a request.

Specifying the 1st argument opensocial.IdSpec, it is able to make the specified user initially chosen the default setting. The specification is available as shown below.

var params = {};
params[opensocial.IdSpec.Field.USER_ID] = ["user_id1", "user_id2", ...];
var recipients = opensocial.newIdSpec(params);
opensocial.requestShareApp(recipients, ...);

In the 4th argument, you need to specify the object that has the content to send as a request. You can use the following as the object’s property name.

Constant Meaning
mixi.Request.Field.BODY Specify the default initial script of sent message.
mixi.Request.Field.IMAGE The opensocial.MediaItem object that has the image information, including the message. It is can be omitted.
mixi.Request.Field.FILTER_TYPE The user classification for the request target. It is specified by the constant defined by the mixi.Request.FilterType object.
mixi.Request.Field.URL The link URL when the user clicks the request.(for PC, Touch)
mixi.Request.Field.MOBILE_URL The link URL when the user clicks the request(for Mobile)
mixi.Request.Field.TARGET_USERS It is specified when you want to limit the user displayed in the pop-up window.
mixi.Request.Field.DESCRIPTION It is used when you want to change the description displayed in the pop-up window.

The link URL must be specified for running the application.

You can specify the user classification displayed in the pop-up window depending on FILTER_TYPE. The specified value is as shown below.

Constant Meaning
mixi.Request.FilterType.JOINED_ONLY Only friends who join the app.
mixi.Request.FilterType.NOT_JOINED_ONLY Only friends who do not join the app.
mixi.Request.FilterType.BOTH All friends

In the pop-up window displayed when requestShareApp() function is executed, thr mixi.Request.Field.TARGET_USERS constant is used if you want to limit the displayed friends. Regarding the specification, you need to create the opensocial.IdSpec object. For example, after executing the following codes only, two friends of user ID “xxxxxxxx” and “yyyyyyyy” are displayed. The limit of specified users is the number of friend users.

var reqParams = {};
var targetUsersIdSpecParams = {};
targetUsersIdSpecParams[opensocial.IdSpec.Field.USER_ID] = ["xxxxxxxx", "yyyyyyyy"];
var targetUsers = opensocial.newIdSpec(targetUsersIdSpecParams);
reqParams[mixi.Request.Field.TARGET_USERS] = targetUsers;
opensocial.requestShareApp(recipients, null, function(response) {...}, reqParams);

If you want to change the description displayed by each application in the pop-up window at the top, please specify the mixi.Request.Field.DESCRIPTION as shown below.

var reqParams = {};
reqParams[mixi.Request.Field.DESCRIPTION] = "ギフトを贈りたい人を15人までで選択してください!";
opensocial.requestShareApp(recipients, null, function(response) {...}, reqParams);

After closing the pop-up window, the callback function given on the 3rd argument is called. You are able to execute it later in the callback function.

Sent User and obtained Request ID

You may want to know the user sent to on some mixi apps. From the callback function specified in the requestShareApp() function, you can determine the friends ID chosen and set by the user. Also, you can obtain the Request ID created at the same time. The Request ID can be held by the SAP side and available when you want to delete the target request.

opensocial.requestShareApp(..., function(response) {
  if (response.hadError()){
    // エラー時の処理
    var code = response.getErrorCode();
    var msg = response.getErrorMessage();
  else {
    // 成功時の処理
    var data = response.getData();
    var recipientIds = data["recipientIds"];
    var requestId = data["requestId"];
}, params);

The given argument for the callback function is opensocial.ResponseItem. The recipientIds property value, which has the result of calling getData() function, is the friend’s user ID array chosen and set by the user. If the parameter when calling the opensocial.requestShareApp() function is wrong, the request is not sent and the user ID array is not obtained.

If another error occurs, obtain the error information with opensocial.ResponseItem object’s hadError() function and the getErrorCode() function. The anticipated error code is as shown below.

Error code Error message Circumstance
401 Insufficient scope User permission of mixi_apps2 scope is not obtained.

Deleting the sent request

If the user who received a request from friends runs the app directly without receiving the request, the request held in mixi remains and is inconsistent. Also, when the sent request expires in the mixi app, you may want to delete the expired request held by mixi from the app.

To delete the request from the app, you need to use Request Delete API prepared for the mixi Graph API. For more details, please refer to Request Delete API.