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

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

リクエストAPI利用の事前準備

リクエストAPIを利用するには、以下の事前準備をしておく必要があります。

• JavaScript API で提供されていますので、JavaScript API の利用準備を行っておく必要があります
• 利用には mixi_apps2 スコープのユーザ認可を取得しておく必要があります
  ユーザ認可の方法についてはユーザ認可についてをご参照ください

リクエストの送信

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

var data = {};
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("VIEWER_FRIENDS", null, function(response) {...}, reqParams);

appParamsはJSON形式で表しURIエスケープします。
appParams以外のパラメータ名を指定した場合でもアプリの起動URLとしてパラメータは付与されますが、
mixi アプリ for TouchにおいてはappParamsで指定したパラメータのみバックエンドサーバへ送信されます。
（例：「{"uid":"1569"}」をURIエスケープして「%7B%22uid%22%3A%221569%22%7D」）

appParams=%7B%22uid%22%3A%221569%22%7D

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

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

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

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

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

エラーが発生した場合には、コールバック関数に渡される引数よりhadError()関数、およびgetErrorCode()関数でエラー情報を取得することができます。以下に発生する可能性のあるエラーコードを示します。

リクエストの削除

送信されたリクエストをSAP側から削除する際には、mixi Graph API に用意されたリクエスト削除APIを利用します。詳細についてはリクエスト削除APIをご参照ください。