ゲームリクエスト

ゲームリクエストにより、プレイヤーが友達をゲームに招待するメカニズムが実現しています。リクエストは、プレイヤーから1人または複数の友達に送信され、ゲームのコールトゥーアクションを必ず含みます。リクエストは、既存のプレイヤーにも新しいプレイヤーにも送信できます。

ゲームリクエストは、新しいプレイヤーを引き付けたり、既存のプレイヤーを呼び戻したりするために利用できます。リクエストは以下の2つのシナリオで送信できます。

1. リクエストの受信者は、送信者の友達で、まだゲームを認証していない。このシナリオは、招待する場合に適しています。
2. リクエストの受信者は、送信者の友達で、以前にゲームを認証している。このシナリオは、ターン制ゲームのお知らせを送る場合や助けを求める場合に適しています。

リクエストは送信者がゲーム中に送信され、Facebookの複数の場所で受信者に表示されます。リクエストは常に非公開で、受信者だけに表示されます。1つのリクエストを一度に複数の受信者に送信できますが、リクエストの受信者には送信者の詳細のみが表示され、他のリクエスト受信者については一切表示されません。

デスクトップ用Facebookで表示されるゲームリクエストの例。

ゲームリクエストは、iOSとAndroidのFacebookゲームやモバイルゲームで利用できます。Facebookデスクトップサイトでは、リクエストはお知らせの印や、画面左下でベル付きのポップアップとして表示されます(フィルターされていない場合)。モバイルプラットフォームでは、Facebookアプリのお知らせリストで表示されます(フィルターされていない場合)。リクエストデータは、ゲームリクエストAPIを介して入手できます。カスタムUIを組み込むと、モバイルゲーム内のエクスペリエンスがさらに統一感のあるものになります。そのためには、リクエストの実装はプラットフォームに依存しないものとし、どのプラットフォームでも一貫したユーザーエクスペリエンスを提供する必要があります。ただし、プレイヤーが送信した招待は、ゲームでサポートされていればどのようなプラットフォームの組み合わせでも表示されます。

リクエストダイアログの起動

ゲームリクエストダイアログは、JavaScript、iOS、Android、Unity SDKを使って生成されます。これらの例では、送信者がアプリを認証していることを前提としています。受信者が指定されていない場合、友達リストを50人以下に絞り込むようにフィルターを適用できます。また、登録済みプレイヤーや未登録の友達で区分できます。これは、再エンゲージメントと招待用で個別のフローを提供するのに便利です。

JavaScript

ゲームリクエストダイアログで提供される、マルチ友達セレクターを使ってリクエストを送信します。

FB.ui({method: 'apprequests',
  message: 'YOUR_MESSAGE_HERE'
}, function(response){
  console.log(response);
});

ダイアログを閉じると、responseオブジェクトには、request IDやto受信者の配列などの情報がある送信結果が含まれます。以下はその例です。

{
  "request":"1428237347457728",
  "to":["10150002163885335"]
}

デフォルトでは、送信者にマルチ友達セレクターが表示されます。そのセレクターを使って、最大で50人の受信者を選べます。

特定の受信者にリクエストを送信するには次のようにします。

FB.ui({method: 'apprequests',
  message: 'YOUR_MESSAGE_HERE',
  to: 'USER_ID'
}, function(response){
  console.log(response);
});

toフィールドを指定すると、送信者は追加の受信者を選べなくなります。

特定の複数の受信者にリクエストを送信するには次のようにします。

FB.ui({method: 'apprequests',
  message: 'YOUR_MESSAGE_HERE',
  to: 'USER_ID, USER_ID, USER_ID'
}, function(response){
  console.log(response);
});

ユーザーIDのコンマ区切りリストを使用して、複数の受信者を指定できます。

特定の友達リストにリクエストを送信するには次のようにします。

FB.ui({method: 'apprequests',
  message: 'Friend Smash Request!',
  filters: [{name:'GROUP_1_NAME', user_ids:['USER_ID','USER_ID','USER_ID']},{name:'GROUP_2_NAME', user_ids: ['USER_ID','USER_ID','USER_ID']}]
}, function(response){
  console.log(response);
}});

action_typeとobject_idを明確に指定して、リクエストでオブジェクトを送信するには次のようにします。

FB.ui({method: 'apprequests',
  message: 'Take this bomb to blast your way to victory!',
  to: {user-ids},
  action_type:'send',
  object_id: 'YOUR_OBJECT_ID'  // e.g. '191181717736427'
}, function(response){
  console.log(response);
});

ターンベース型リクエストの場合は、object_idを指定しないでください。

FB.ui({method: 'apprequests',
  message: 'Just smashed you 78 times! It\'s your turn.',
  to: {user-ids},
  action_type:'turn'
}, function(response){
  console.log(response);
});

または、受信者を名前を付けたリストに分けることができます。こうすればプレイヤーは、ゲームでの状況に基づいて論理的にグループ分けされた友達の中から友達を選べます。

詳しくは、Facebook SDK for JavaScriptのFB.uiリファレンスドキュメントをご覧ください。

iOS SDK

iOS SDKが提供する友達セレクターを使ってリクエストダイアログを起動するには次のようにします。

FBSDKGameRequestContent *gameRequestContent = [[FBSDKGameRequestContent alloc] init];
// Look at FBSDKGameRequestContent for futher optional properties
gameRequestContent.message = @"YOUR_MESSAGE_HERE";
gameRequestContent.title = @"OPTIONAL TITLE";

// Assuming self implements <FBSDKGameRequestDialogDelegate>
[FBSDKGameRequestDialog showWithContent:gameRequestContent delegate:self];

iOS SDKを使って、action_typeとobject_idを明確に指定したリクエストを、特定の受信者に送信するには次のようにします。

FBSDKGameRequestContent *gameRequestContent = [[FBSDKGameRequestContent alloc] init];
gameRequestContent.message = @"Take this bomb to blast your way to victory!";
gameRequestContent.to = @[@"RECIPIENT_USER_ID"];
gameRequestContent.objectID = @"YOUR_OBJECT_ID";
gameRequestContent.actionType = @"ACTION_TYPE";

// Assuming self implements <FBSDKGameRequestDialogDelegate>
[FBSDKGameRequestDialog showWithContent:gameRequestContent delegate:self];

Android SDK

Android SDKからリクエストダイアログ友達セレクターを使ってリクエストを送信するには次のようにします。

GameRequestDialog requestDialog;
CallbackManager callbackManager;

public void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  FacebookSdk.sdkInitialize(this.getApplicationContext());
  callbackManager = CallbackManager.Factory.create();
  requestDialog = new GameRequestDialog(this);
  requestDialog.registerCallback(callbackManager,
    new FacebookCallback<GameRequestDialog.Result>() {
    public void onSuccess(GameRequestDialog.Result result) {
      String id = result.getId();
    }
    public void onCancel() {}
      public void onError(FacebookException error) {}
    }
  );
}

private void onClickRequestButton() {
  GameRequestContent content = new GameRequestContent.Builder()
    .setMessage("Come play this level with me")
    .build();
  requestDialog.show(content);
}

protected void onActivityResult(int requestCode, int resultCode, Intent data) {
  super.onActivityResult(requestCode, resultCode, data);
  callbackManager.onActivityResult(requestCode, resultCode, data);
}

Android SDKを使って、アクションとオブジェクトを明確に指定したリクエストを送信するには次のようにします。

private void onClickRequestButton() {
  GameRequestContent content = new GameRequestContent.Builder()
    .setMessage("Come play this level with me")
    .setTo("USER_ID")
    .setActionType(ActionType.SEND)
    .setObjectId("YOUR_OBJECT_ID")
    .build();
  requestDialog.show(content);
}

Unity SDK

ここでは、Unity SDKでリクエストがどのように実行されるかを示します。詳しくは、FB.AppRequestのドキュメントをご覧ください。

FB.AppRequest(
  message: "I Just got " + GameStateManager.Score.ToString() + " points! Can you beat it?",
  to: recipients,
  data: "{\"challenge_score\":" + GameStateManager.Score.ToString() + "}"
  title: "Friend Smash Challenge!",
  callback:appRequestCallback
);

ダイアログのパラメーター

ゲームリクエストダイアログは、動作を決定するさまざまな追加パラメーターを使って作成できます。これらのパラメーターについて以下に説明します。

応答データ

リクエストがゲームリクエストダイアログを介して送信されると、以下の情報を含むコールバックに応答が渡されます。

ゲーム内でのリクエストの処理

リクエストの受け入れ

受信者がFacebookデスクトップサイトでリクエストを受け入れると、リクエストが送信されたゲームのURLにリダイレクトされます。このURLには、追加のGETパラメーターであるrequest_idsを含めます。これは、ユーザーが受け入れたリクエストIDのコンマ区切りリストです。

http://apps.facebook.com/[app_name]/?request_ids=[REQUEST_IDs]

受信者がリクエストを受け入れると、リクエストは自動では削除されません。これはゲーム側で対応する必要があります。ゲーム起動時に、そのユーザーの未処理リクエストのリストをグラフAPIから読み取り、処理後にそれぞれを削除する方法が一般的です。

受信者がモバイルプラットフォームでリクエストを受け入れると、アプリにディープリンクされます。アプリのロード中、リクエストIDという追加パラメーターが表示されます。リクエストの受け入れとクリアの処理はモバイルでも同様にゲーム側が行います。ゲーム起動時に、処理待ちリクエストを確認してクリアすることをおすすめします。

リクエストの読み取り

送信される各リクエストには、一意のリクエストオブジェクトIDがあります。このIDは、リクエストオブジェクトを表します。このリクエストオブジェクトIDを受信者のユーザーIDと連結して、このリクエストに固有のインスタンスを作成できます。これは、特定の受信者に送信されたリクエストをインスタンス化したものです。

たとえば、リクエストを送信すると、ゲームリクエストダイアログからの応答は次のようになります。

{
  request: 'REQUEST_OBJECT_ID'
  to:[array of USER_IDs]
}

グラフAPIを使ってリクエストオブジェクトIDを調べる場合、受け取る応答は検索の表示コンテキストによって若干異なりますが、応答は常にリクエストオブジェクト全体を表します。

たとえば、受信者のユーザーアクセストークンを使って、http://graph.facebook.com/{REQUEST_OBJECT_ID}?access_token=USER_ACCESS_TOKENにクエリを実行すると、以下のような応答になります。

{
  "id": "REQUEST_OBJECT_ID",
  "application": {
    "name": "APP_DISPLAY_NAME",
    "namespace": "APP_NAMESPACE",
    "id": "APP_ID"
  },
  "to": {
    "name": "RECIPIENT_FULL_NAME",
    "id": "RECIPIENT_USER_ID"
  },
  "from": {
    "name": "SENDER_FULL_NAME",
    "id": "SENDER_USER_ID"
  },
  "message": "ATTACHED_MESSAGE",
  "created_time": "2014-01-17T16:39:00+0000"
}

toフィールドとfromフィールドの両方が返されていることに注意してください。ただし、送信者のアクセストークンやアプリのアクセストークンを使って同じエンドポイントを呼び出すと、以下が返されます。

{
  "id": "REQUEST_OBJECT_ID",
  "application": {
    "name": "APP_DISPLAY_NAME",
    "namespace": "APP_NAMESPACE",
    "id": "APP_ID"
  },
  "from": {
    "name": "SENDER_FULL_NAME",
    "id": "SENDER_USER_ID"
  },
  "message": "ATTACHED_MESSAGE",
  "created_time": "2014-01-17T16:39:00+0000"
}

アプリのアクセストークンを使って受信者を含む完全なリクエストを取得するには、リクエストオブジェクトIDの後ろにアンダースコア「_」と受信者のユーザーIDを追加する必要があります。たとえば、https://graph.facebook.com/{REQUEST_OBJECT_ID}_{USER_ID}?access_token={APP_ACCESS_TOKEN}への呼び出しでは以下が返されます。

{
  "id": "REQUEST_OBJECT_ID",
  "application": {
    "name": "APP_DISPLAY_NAME",
    "namespace": "APP_NAMESPACE",
    "id": "APP_ID"
  },
  "to": {
    "name": "RECIPIENT_FULL_NAME",
    "id": "RECIPIENT_USER_ID"
  },
  "from": {
    "name": "SENDER_FULL_NAME",
    "id": "SENDER_USER_ID"
  },
  "message": "ATTACHED_MESSAGE",
  "created_time": "2014-01-17T16:39:00+0000"
}

すべてのリクエストの読み取り

受信者のすべてのリクエストを読み取るには、受信者のUSER ACCESS TOKENを使って、以下に示すようにグラフ対してクエリを実行します。これにより、そのユーザーのアプリ内のリクエストIDのリストが返されます。

GET https://graph.facebook.com/me/apprequests?access_token=[USER ACCESS TOKEN]

リクエストの削除

受信者がゲームリクエストを受け入れると、リクエストは自動的に削除されません。リクエスト受け入れ後に削除する処理は、開発者側で行う必要があります。開発者は、リクエストが受け入れられたら、プレイヤーに代わってリクエストを削除する必要があります。

以下の方法でリクエストを削除できます。

グラフAPI

連結されたrequest_idに対してHTTP DELETEリクエストを発行します。

DELETE https://graph.facebook.com/[{REQUEST_OBJECT_ID}_{USER_ID}]?
      access_token=[USER or APP ACCESS TOKEN]

JavaScript

function deleteRequest(requestId) {
  FB.api(requestId, 'delete', function(response) {
    console.log(response);
  });
}

リファーラルと特典のリクエストのトラッキング

受信者が結果的に行う特定のアクションに基づいて、ゲームリクエストの送信者に特典を提供できます。たとえば、リクエストを送信するだけではプレイヤーに特典を提供できませんが、リクエストを受け入れた結果、受信者がゲームをインストールして特定のレベルに到達した場合は、送信者に特典を提供できます。

送信者に特典を提供するには、だれに特典を付与するべきかを把握できなければなりません。これには、次の2つの方法があります。

1. リクエストを送信する際、ゲームリクエストダイアログから応答で返されたrequest_idを保存し、受信時にそれを照合して送信者に特典を提供します。
2. プレイヤーがゲームを起動したとき、プレイヤーのすべてのリクエストを読み取り、リクエストのfromフィールドにあるidに基づいて送信者に特典を提供します。複数の友達が同じ1人のプレイヤーを招待した場合、招待を最初に送った友達に特典を付与するかすべての友達に特典を付与するか選べます。

招待可能な友達API

ローカリゼーション

世界中のオーディエンスに最適なサービスを提供できるように、Facebookではrequestsのローカリゼーション機能をサポートしています。リクエストを翻訳する前に、リクエストのさまざまなタイプとその表示方法の違いを知っておくことが重要です。リクエストは標準的な「Anita sent you a request (Anitaさんからリクエストが届きました)」や、アクション/オブジェクトのペアが指定されている場合は、「Anita asked you for a Life (Anitaさんから救命の依頼がありました)」や「Anita sent you a Bomb (Anitaさんから爆弾が届きました)」のように表示されます。友達と対戦するゲームでは、その人の順番が来たことを知らせるターンリクエストもあります。ゲームを認証したプレイヤーには、これらすべての例が表示されます。受信者がゲームをインストールしていない場合は、その人には招待の形でリクエストが表示されます。たとえば、「Anita invited you to play Friend Smash! (AnitaさんからFriend Smash!をプレイするよう招かれました)」などです。それぞれの翻訳方法を見てみましょう。

招待の翻訳

招待のテキストはFacebookによって自動翻訳されます。開発者は制御できません。受信者の言語に翻訳されます。

英語の招待のお知らせ

タイ語の招待のお知らせ

上記の例では、「invited you to play」というテキストは自動的に別の言語(ここではタイ語)に翻訳されます。アプリの名前と説明は、[アプリ設定]の[ローカライズ]セクションの以下の黄色い枠内の[表示名]と[説明]に翻訳されます。

アプリの表示名と説明の翻訳

リクエストはアプリセンターにも表示されます。アプリセンターで、リクエストの「メッセージ」が表示されます。このメッセージは開発者が翻訳できます。以下の例で、「Can I have a life to help me through the next level?」という英語のメッセージは、タイ語では「ช่วยส่งตัวเพิ่มให้หน่อย ต้องใช้ไปเลเวลหน้า」となります。現時点では、リクエストのメインテキストである「Anita sent you a request」はアプリセンターでは表示されません。

アプリセンターの英語のリクエスト

アプリセンターのタイ語のリクエスト

メッセージの翻訳

メッセージはリクエストダイアログが呼び出されたときにパラメーターとして渡されるため、リクエストダイアログを呼び出す前に開発者が翻訳しておけば、その翻訳した文字列をメッセージとして渡せます。翻訳を動的に変更する場合は、ダイアログを呼び出す前に変更します。このテキストは、リクエストプレビューで送信者に表示されるテキストや受信者がリクエストを受け取ったときに表示されるテキストと同じになり、どの言語で表示するかは開発者が決定します。

多くの開発者は、送信者のロケールを検出して、その情報を基にメッセージに使用する言語を決定しています。ほとんどの場合、開発者は、送信者と受信者の使用言語は同じであると想定します。上記の例では、送信者のロケールを確認して、それがタイ語であれば、以下のようにタイ語の文字列をメッセージとして直接送信できます。

FB.ui({method: 'apprequests',
  message: 'ช่วยส่งตัวเพิ่มให้หน่อย ต้องใช้ไปเลเวลหน้า'
}, requestCallback);

ベストプラクティス

リクエストにデータを付加する

前述のダイアログパラメーターセクションで触れたように、リクエストに最大255文字の追加データを付加して送信できます。この機能を使って、リクエストに関する追加情報を転送したり、サーバーに保管されている関連情報を後から検索する際に利用できる識別子を付加したりできます。

たとえば、FacebookサンプルゲームプロジェクトであるFriend Smashでは、プレイヤーはできる限り多くの友達を「スマッシュ」できるよう交代で競い合います。あるプレイヤーがリクエストを送って別のプレイヤーに対戦を申し込むと、そのデータパラメーターを使って対戦を申し込んだプレイヤーの最新スコアが保存されます。ゲームが始まると、受け取り側プレイヤーのこの値を抽出し、それを次のゲームの目標スコアにします。

招待のフィルター

カスタムのマルチ友達セレクターを構築する場合や、その他の方法でリクエストの送信先を選択する場合は、プレイヤーが簡単に希望する受信者を選べるようにするためフィルターの導入を検討してください。

ゲームリクエストダイアログを使う招待を実装する場合に使う一般的なフィルターは、app_non_usersです。このフィルターを使うと、以前そのゲームをプレイしたことがある人は、ゲームリクエストダイアログに表示されなくなります。最近やり取りがあったプレイヤーや、あなたが管理している似たようなゲームのプレイヤーなどをフィルターすることも考慮できます。利用できるフィルターの全一覧については、ゲームリクエストダイアログ - パラメーターに関するリファレンスドキュメントをご覧ください。

エンゲージメントを高めるメカニズムを作り出す

プレイヤーがゲーム内で友達を訪問したり友達と直接交流したりする際に、エンゲージメントを高めるメカニズムを作りましょう。たとえば、ゲームで近隣者の概念がサポートされている場合、プレイヤーが近隣者の環境を訪問したときに、ボーナスエネルギーを与えます。プレイヤーの基地が攻撃された場合は、その友達が修復を手助けできるようにします。一般的にプレイヤーは友達の成長を助けることに意義を感じるため、そのような機会を与えれば、ソーシャルエクスペリエンスを向上させてより多くのプレイヤーを呼び込むことができます。

オブジェクトをプレイヤーにとって価値あるものにする

ゲームプレイの強化やソーシャルエクスペリエンスの向上に役立つような価値あるものをプレイヤーに提供しましょう。

プレイヤーをセグメント化して状況に応じたリクエストを提供する

ゲームにとって意味がある範囲でプレイヤーを分類しましょう(新規プレイヤー、アイテム生産を行うプレイヤー、友達の多いプレイヤー、ヘビープレイヤーなど)。各グループのプレイヤーのレベルでどのようなものが役立つかを考えて、各グループに合わせたギフトを提供します。