新リクエストAPIを使ってみよう << mixi Developer Center (ミクシィデベロッパーセンター)

mixi アプリから新リクエストAPI を利用するためには、 mixi.requestShareApp() 関数を利用します。この関数を呼び出すことによって、友人やアプリのプレーヤーに対して要求を送信することが可能です。この requestShareApp() 関数は、旧リクエストAPI や、招待を送信する際に使用する関数が含まれる opensocial オブジェクトと異なり、 mixi オブジェクトに含まれます。

var targetUsersIdSpecParams = {};
targetUsersIdSpecParams[opensocial.IdSpec.Field.USER_ID] = ["user_id1", "user_id2", ...];
var targetUsers = opensocial.newIdSpec(targetUsersIdSpecParams);
var image = opensocial.newMediaItem("image/gif", "https://sample.server.name/image.gif");
var params = {};
params[mixi.PushRequest.Field.TITLE] = "近所に引っ越してもらおう";
params[mixi.PushRequest.Field.IMAGE] = image;
params[mixi.PushRequest.Field.DESCRIPTION] = "近所に引っ越してもらいたい人にメッセージを贈ろう！";
params[mixi.PushRequest.Field.TARGET_USERS] = targetUsers;
params[mixi.PushRequest.Field.URL] = "http://mixi.jp/run_appli.pl?id=[アプリID]&appParams=...";
params[mixi.PushRequest.Field.BODY] = "ご近所さんになってください"
mixi.requestShareApp(params, function (response) {
 　 if (response.hadError()) {
        var code = response.getErrorCode();
        if (code == 400) {
            // Bad Request
        } else if (code == 401) {
            // Unauthorized
        } else if (code == 403) {
           // User canceled
        } else if (code == 500) {
          // Internal server error
        }
    } else {
        var data = response.getData();
        var recipientIds = data.recipientIds;
        var requestId = data.requestId;
        // success
    }
});

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

第１引数は、リクエストとして送信したい内容を持つオブジェクトを指定します。
第２引数は、リクエストが送信された後に呼び出されるコールバック関数を指定します。

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

定数名	意味
mixi.PushRequest.Field.TITLE	送信画面のタイトルとしてユーザに表示する文章を指定します。
mixi.PushRequest.Field.IMAGE	メッセージに含める画像の情報を持つopensocial.MediaItemオブジェクト。これは省略することも可能です。 HTTPSの画像PATHを推奨します。
mixi.PushRequest.Field.DESCRIPTION	ポップアップ画面の上部に表示される説明文を変更したい場合に使用します。
mixi.PushRequest.Field.TARGET_USERS	送信したいユーザの ID を指定します。
mixi.PushRequest.Field.URL	リクエストをユーザがクリックした際の飛び先のURL（for PC, Touch）。
mixi.PushRequest.Field.BODY	送信されるメッセージの初期表示文章を指定します。

飛び先のURL指定は、そのアプリを起動するためのURLでなければなりません。
また、 PC, Touch 用の URL ( mixi.PushRequest.Field.URL ) には、パラメーターに appParams を指定することができます。
appParams 以外のパラメータ名を指定した場合でもアプリの起動URLとしてパラメータは付与されますが、
mixi アプリにおいては appParams で指定したパラメータのみバックエンドサーバへ送信されます。
appParams はJSON形式で表しURIエスケープします。
（例：「{"uid":"1569"}」をURIエスケープして「%7B%22uid%22%3A%221569%22%7D」）

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

mixi.PushRequest.Field.TARGET_USERS 定数は、 requestShareApp() 関数を実行した際に送信したいユーザを指定するために使用します。
指定については、 opensocial.IdSpec オブジェクトを生成する必要があります。
例えば、以下のコードを実行した場合は、ユーザID "xxxxxxxx" および "yyyyyyyy" の 2 名のユーザに送信します。

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

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

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

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

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

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

mixi.requestShareApp(params, 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;
    }
});

コールバック関数に渡される引数は opensocial.ResponseItem オブジェクトとなります。
getData() 関数を呼び出し、その結果が持つ "recipientIds" プロパティ値が、ユーザが選択し送信を行ったユーザのユーザIDの配列となります。
opensocial.requestShareApp() 関数呼び出し時のパラメータに誤りがある場合は、リクエストの送信が行われず、ユーザIDの配列を取得することはできません。

その他のエラーが発生した場合には opensocial.ResponseItem オブジェクトの hadError() 関数、および getErrorCode() 関数でエラー情報を取得することができます。
以下に発生する可能性のあるエラーコードを示します。

エラーコード	エラーメッセージ	発生する状況
400	parameter_invalid	パラメータに不備がある
401	Insufficient_scope	mixi_apps2スコープのユーザ認可を取得していない
403	forbidden	ユーザが「やめる」を選択、指定された送信先IDが有効でない
500	internal_error	mixi側の内部エラー

このページの上部へ

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

mixiアプリ

新リクエストAPIを使ってみよう

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

新リクエストを送信する

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

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