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

mixiアプリ

mixiアプリ » 技術仕様(RESTful API方式) » スマートフォン » UserFlow APIの利用 » Request(リクエスト)

Request(リクエスト)

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

リクエストの送信

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

var data = {};
var reqParams = {};
var image = opensocial.newMediaItem("image/gif", "http://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.MOBILE_URL] = "http://ma.mixi.net/[アプリID]/?url=...";
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引数には、リクエストとして送信したい内容を持つオブジェクトを指定します。そのオブジェクトのプロパティ名として、以下のものを使用します。

定数名 意味
mixi.Request.Field.BODY 送信されるメッセージの初期表示文章を指定します。
mixi.Request.Field.IMAGE メッセージに含める画像の情報を持つopensocial.MediaItemオブジェクト。これは省略することも可能です。
mixi.Request.Field.FILTER_TYPE リクエストの対象となるユーザの種別。mixi.Request.FilterTypeオブジェクトに定義された定数にて指定
mixi.Request.Field.URL リクエストをユーザがクリックした際の飛び先のURL(for PC, Touch)
mixi.Request.Field.MOBILE_URL リクエストをユーザがクリックした際の飛び先のURL(for Mobile)
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引数で渡したコールバック関数が呼び出されます。このコールバック関数内で、リクエストに対する後処理を行うことが可能です。

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の配列となります。また、”requestId”プロパティ値として、作成されたリクエストを特定するためのIDを得ることが可能です。

リクエストの削除

送信されたリクエストをSAP側から削除する際には、RESTful APIを使用します。詳しくは以下のページを参照ください。

リクエスト削除API – RESTful API

このページの上部へ