遊戲邀請

「遊戲邀請」提供玩家邀請朋友玩遊戲的機制。要求會由玩家發送給一或多位朋友，且一定包含遊戲相關的行動呼籲。收件人可以是現有玩家或新玩家。

「遊戲邀請」可用於吸引新玩家，或再次與現有玩家互動。發送要求的兩種情況如下：

1. 收件人是寄件人的朋友，而且尚未驗證遊戲。這種情況適合用於邀請。
2. 收件人是寄件人的朋友，且之前已驗證遊戲。這種情況適合用於回合制通知和尋求協助。

要求是由寄件人從遊戲中發送，並且會在 Facebook 上許多位置向收件人顯示。要求一律為私密性質，唯有收件人才可檢視。雖然可同時將單一要求發送給多位收件人，但收件人只會看到寄件人的詳細資料，絕不會看到其他任何收件人。

範例：桌面版 Facebook 顯示的「遊戲邀請」。

Facebook 上的遊戲和 iOS 與 Android 版手機遊戲都可使用「遊戲邀請」。在 Facebook 桌面版網站，如果未遭系統篩選，要求會在畫面左下角顯示為彈出的呼叫器，也會顯示在通知圖示。在行動平台，如果要求未遭系統篩選，則會顯示在 Facebook 應用程式的通知清單。透過「遊戲邀請 API」可取得要求資料，您也可建置自訂用戶介面，為行動版遊戲提供更整體的體驗。因此，要求的實作方式應該與平台無關，而且不論平台為何，必須提供一致的用戶體驗。不過，玩家發送的邀請會出現在遊戲支援的所有平台組合上。

啟動「邀請」對話方塊

「遊戲邀請」對話方塊可透過 JavaScript、iOS、Android 和 Unity SDK 產生。以下範例假設寄件人已驗證應用程式。若未指定收件人，您可篩選朋友清單，以限制在 50 位朋友以下，並可按已註冊玩家或未註冊朋友劃分。這對於針對再次互動或邀請提供個別的流程很有幫助。

JavaScript

使用「遊戲邀請」對話方塊提供的朋友複選器發送要求：

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

對話方塊關閉時，response 物件會包含發送結果，其中包括 request 編號和 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);
});

若要指定多位收件人，可在清單輸入用戶編號並以逗號分隔。

發送要求給特定朋友清單：

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 JavaScript SDK 中有關 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 桌面版網站接受要求後，就會被帶往發送要求的遊戲網址。此網址會包含額外的 GET 參數 request_ids，這是有接受要求的用戶編號清單（以逗號分隔）：

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

收件人接受要求後，要求並不會自動刪除。這必須由遊戲負責處理。常見作法是：在遊戲啟動時，針對該用戶從圖形 API 讀取未處理的要求清單，然後在處理後一一刪除。

收件人在行動平台上接受要求後，便會深層連結至應用程式。載入應用程式時，會存在一個額外參數：要求編號。在行動平台上同樣必須負責接受和清除要求。在遊戲啟動時，檢查並清除未處理的要求，是良好的作法。

讀取要求

每個發送的要求都有唯一的要求物件編號。這個編號代表該要求物件。此要求物件編號可串連收件人用戶編號，以建立要求的特定執行個體。這代表已發送給特定收件人的要求執行個體。

例如，發送要求時，「遊戲邀請」對話方塊的回應會類似如下範例：

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

如果透過圖形 API 查詢要求物件編號，視查詢的檢視內容而定，所收到的回應會稍有不同，但回應一定會代表整個要求物件。

舉例來說，如果對 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 欄位都會傳回。然而，如果使用寄件人的存取權杖（或應用程式存取權杖）來呼叫相同端點，Facebook 會傳回以下回應：

{
  "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"
}

如果要求中包含使用應用程式存取權杖的收件人，若要取得完整要求，必須在底線「_」字元之後附加收件人用戶編號。例如，對 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 查詢開放社交關係圖。如此會傳回應用程式中該用戶的要求編號清單。

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

針對轉介和獎勵追蹤要求

您可根據收件人執行的特定動作，獎勵「遊戲邀請」的寄件人。舉例來說，您不可因為單純發送要求而獎勵玩家，但如果收件人因為接受要求而安裝遊戲，並完成特定關卡，您就能獎勵寄件人。

若要獎勵寄件人，您必須先找出該獎勵的對象，有兩種作法可供您選擇：

1. 發送要求時，儲存「遊戲邀請」對話方塊的回應中傳回的 request_id，然後在收到時加以比對，以獎勵寄件人。
2. 啟動遊戲時，針對玩家讀取所有要求，然後根據邀請 from 欄位中的 id來獎勵寄件人。如果多位朋友都邀請某位玩家，您可選擇獎勵首位寄件人或所有寄件人。

朋友邀請功能 API

本地化

為協助您為全球用戶提供最佳的用戶體驗，Facebook 支援 requests 的本地化。在翻譯要求前，務必先瞭解要求的各種類型，以及所顯示的方式。要求可顯示為標準的「小美寄給你 1 則邀請」，或若已指定動作／物件組，則可為「小美要求你提供 1 條生命」或「小美寄給你 1 個炸彈」。還有一種回合要求，讓用戶知道在與朋友的對戰中輪到他們上場。所有這些範例已認證遊戲的玩家都會看到。如果收件人尚未安裝遊戲，就會以邀請的形式看到要求。例如，「小美邀請你玩好友鬥陣去！」。讓我們看看如何翻譯這些邀請。

翻譯邀請

Facebook 會自動翻譯邀請文字，開發人員沒有任何控制權。邀請會翻譯為收件人所用語言。

以英語顯示的邀請通知

以泰語顯示的邀請通知

請注意在以上範例中，「invited you to play」文字會自動翻譯為另一種語言（此例為泰語）。應用程式名稱和說明會翻譯為應用程式設定的「本地化」區塊中的「顯示名稱」和「說明」，如以下黃色方塊所示。

翻譯應用程式的顯示名稱和說明

要求也會顯示在應用程式中心。應用程式中心會顯示要求的「訊息」。開發人員可翻譯該訊息。在以下範例中，訊息以英語顯示為「Can I have a life to help me through the next level?」，以泰語顯示為「ช่วยส่งตัวเพิ่มให้หน่อย ต้องใช้ไปเลเวลหน้า」。應用程式中心目前不會顯示要求的主要內文：「小美寄給你 1 則邀請」。

應用程式中心的要求（英語）

應用程式中心的要求（泰語）

翻譯訊息

因為叫用要求對話方塊時，訊息是以參數的方式傳入，所以您可先自行翻譯訊息，再叫用要求對話方塊，同時將翻譯的字串傳遞為訊息。如果想要以動態方式變更翻譯，您應該先進行變更再叫用對話方塊。因為這些文字會與寄件人在要求預覽和收件人在收到要求時所看到的文字相同，您可自行決定要以何種語言顯示。

許多開發人員會偵測寄件人的語言設定，然後以此決定訊息要採用何種語言。開發人員會假設在大部分情況下寄件人和收件人說相同的語言。在以上範例中，您可先查看寄件人的語言設定，若為泰語，就可直接將泰語字串傳遞為訊息，如下所示：

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

最佳作法

將資料附加至要求

如以上對話方塊參數一節所述，發送要求時，您可附加最多 255 個字元的額外資料。您可利用此方式傳輸與要求相關的其他資訊，或附加識別碼，以便之後用於查詢伺服器上儲存的相關資訊。

舉例來說，在 Facebook 遊戲專案範例「好友鬥陣去」中，玩家輪流挑戰「摧毀」最多數量的朋友。當某位玩家透過要求發送挑戰給另一位玩家，資料參數會用於儲存發送挑戰玩家的最新分數。然後，遊戲會為接受挑戰的玩家擷取該值，並使其成為遊戲下一回合的目標分數。

篩選邀請

建置自訂的朋友複選器，或以其他方式選擇向誰發送要求時，請考慮提供篩選條件，以協助玩家選擇所需的收件人。

使用「遊戲邀請」對話方塊實作邀請時，常用的篩選條件為 app_non_users 篩選條件。此篩選條件可避免「遊戲邀請」對話方塊顯示之前已玩過該遊戲的用戶。其他可考慮使用的篩選條件為最近有互動的玩家，或您所控制類似遊戲的玩家。如需可用篩選條件的完整清單，請參閱「遊戲邀請」對話方塊 - 參數參考文件。

建立互動機制

建立當玩家在遊戲中造訪朋友或與朋友直接互動時，可供使用的互動機制。例如，如果遊戲支援鄰居的概念，當玩家造訪鄰居環境時，贈與額外能量。如果玩家的基地遭到攻擊，讓朋友能協助修復。玩家通常對於協助朋友進展覺得很有意義，所以讓玩家有機會這麼做，不但會打造更棒的社交體驗，還會吸引更多用戶參與遊戲。

創造對玩家有價值的物件

提供對玩家有價值的物件，像是可用於提升遊戲玩法或社交體驗的物件。

根據情境劃分玩家並提供要求

評估玩家並將其分為各種對遊戲有意義的群組（例如，新玩家、做工匠的玩家、有很多朋友的玩家、互動程度高的玩家等）。思索對玩家程度而言哪些類型的事物對他們有用，然後針對各個族群提供特定事物。