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

mixiアプリ

mixiアプリ » 技術仕様(Graph API方式) » PC » リクエストAPIを使ってみよう

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

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

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

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

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

リクエストを送信する

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

定数名意味
mixi.Request.Field.BODY 送信されるメッセージの初期表示文章を指定します。
mixi.Request.Field.IMAGE メッセージに含める画像の情報を持つopensocial.MediaItemオブジェクト。これは省略することも可能です。
HTTPSの画像PATHを推奨します。
mixi.Request.Field.FILTER_TYPE リクエストの対象となるユーザの種別。mixi.Request.FilterTypeオブジェクトに定義された定数にて指定。
mixi.Request.Field.URL リクエストをユーザがクリックした際の飛び先のURL(for PC, Touch)。
mixi.Request.Field.TARGET_USERS 友人の中から、ポップアップ画面に表示するユーザを限定したい場合に指定します。
mixi.Request.Field.DESCRIPTION ポップアップ画面の上部に表示される説明文を変更したい場合に使用します。

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

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

定数名意味
mixi.Request.FilterType.JOINED_ONLY このアプリをJoinしている友人のみ。
mixi.Request.FilterType.NOT_JOINED_ONLY このアプリをJoinしていない友人のみ。
mixi.Request.FilterType.BOTH 全友人。

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

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

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

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

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

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

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

エラーコードエラーメッセージ発生する状況
401 Insufficient scope mixi_apps2 スコープのユーザ認可を取得していない

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

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

アプリからリクエストを削除するには、mixi Graph API に用意されたリクエスト削除APIを利用します。詳細についてはリクエスト削除APIをご参照下さい。

このページの上部へ