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

新リクエスト API を利用することで、ユーザは、友人やアプリのプレーヤーに「近所になってください」「花束を贈りますので受け取ってください」といった要求を送信することができます。
また、それらリクエストを、 Push通知 や メール 等で、ユーザーへお知らせすることができます。

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

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

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

リクエストの送信

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() 関数の引数は、以下となります。

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

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

飛び先のURL指定は、そのアプリを起動するためのURLでなければなりません。
また、 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 名のユーザに送信します。

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

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

送信したユーザおよびリクエスト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() 関数でエラー情報を取得することができます。
以下に発生する可能性のあるエラーコードを示します。