mixi Developer Center (ミクシィ デベロッパーセンター)

リクエストAPIを利用することで、ユーザは友人に「花束を贈りますので受け取ってください」といった要求を送信することができます。

リクエストを送信する

mixiアプリからリクエストAPIを利用するためには、opensocial.requestShareApp()関数を利用します。この関数を呼び出すことによって、友人に対して要求を送信することが可能です。このrequestShareApp関数は、招待を送信する際に使用する関数と同じです。

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", "https://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.BODY] = "花束を贈りますので受け取ってください";
opensocial.requestShareApp(recipients, null, function(response) {...}, reqParams);

requestShareApp()関数の引数は、以下となります。

• 第1引数は、"VIEWER_FRIENDS"またはopensical.IdSpecオブジェクトを指定します。
• 第2引数は、送信されるメッセージの初期表示文章を指定します。nullが指定された際には、mixi.Request.Field.BODYにて指定された文字列が使用されます。
• 第3引数は、リクエストが送信された後に呼び出されるコールバック関数を指定します。
• 第4引数は、リクエストとして送信したい内容を持つオブジェクトを指定します。

第1引数にopensocial.IdSpecオブジェクトを指定することで、プログラムから指定ユーザを初期選択状態にすることが可能です。指定は以下のようにして行います。

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

第4引数には、リクエストとして送信したい内容を持つオブジェクトを指定します。そのオブジェクトのプロパティ名として、以下のものを使用します。

飛び先のURL指定は、そのアプリを起動するためのURLでなければなりません。

FILTER_TYPEによって、ポップアップ画面に表示される友人の種別を指定することができます。指定可能な値は以下となります。

mixi.Request.Field.TARGET_USERS定数は、requestShareApp()関数を実行した際に表示されるポップアップ画面において、表示される友人を限定したい場合に使用します。指定については、opensocial.IdSpecオブジェクトを生成する必要があります。例えば、以下のコードを実行した場合は、ユーザID"xxxxxxxx"および"yyyyyyyy"の2名の友人のみが表示されます。指定可能な人数の上限は、そのユーザの友人数となります。

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);

もし各アプリケーションがポップアップ画面の上部に表示される説明文を変更したい場合は、以下のようにしてmixi.Request.Field.DESCRIPTIONを指定します。

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

ポップアップ画面が閉じた後に、第３引数で渡したコールバック関数が呼び出されます。このコールバック関数内で後処理を行うことが可能です。

requestShareApp()関数の利用制限

requestShareApp()関数は、mixiアプリがrun_appli.pl上で動作している場合にのみ利用することが可能です。その他の画面でrequestShareApp()関数を呼び出した場合は、何も処理が行われません（FORBIDDENを持つエラー情報がコールバック関数に渡されます）。

また、requestShareApp()関数は、mixiアプリを実行しているユーザ（Viewer）がそのアプリを所有している必要があります。もし所有していなかった場合は、何も処理が行われません（FORBIDDENを持つエラー情報がコールバック関数に渡されます）。

送信したユーザおよびリクエストIDの取得について

mixiアプリによっては、ユーザが実際に誰に送信したのかを知りたくなることでしょう。requestShareApp()関数に指定したコールバック引数から、ユーザが選択し送信を行った友人のIDを知ることができます。また、同時に作成されたリクエストのIDも得ることができます。リクエストIDはSAP側で保持し、後に対象のリクエストを削除したいときに利用可能です。

opensocial.requestShareApp(..., function(response) {
  var data = response.getData();
  var recipientIds = data["recipientIds"];
  var requestId = data["requestId"];
  // do something...
}, params);

コールバック関数に渡される引数から、getData()関数を呼び出し、その結果が持つ"recipientIds"プロパティ値を取得します。この値は、ユーザが選択し送信を行った友人のユーザIDの配列となります。

送信したリクエストを削除する

友人からのリクエストを受け取ったユーザが、そのリクエストを受け取らずに直接アプリを起動した場合、そのアプリでリクエストに対する処理が行われてしまった時には、mixi内に保持されているリクエストはそのままとなり不整合が生じます。また、送信されたリクエストに期限がアプリ内で設けられていた場合にも、アプリからmixiに保持されている期限切れのリクエストを削除したくなるでしょう。

アプリからリクエストを削除するには、newRemoveUserRequestRequest()関数を利用します。

var req = opensocial.newDataRequest();
req.add(mixi.request.newRemoveUserRequestRequest(
        opensocial.IdSpec.PersonId.VIEWER,
        requestId),
    "del");
req.send(function(data) {
    // do something...
});

newRemoveUserRequestRequest()関数の第1引数は、VIEWERのみ指定可能です。第2引数には、削除したいリクエストの IDを指定します。このリクエストIDは、リクエスト送信時に得られたIDです。この関数で作られたDataRequestオブジェクトをsend()関数にて送信することで、対象リクエストがmixiから削除されます。