遊戲邀請

遊戲邀請為玩家提供了邀請朋友一起參與遊戲的渠道。玩家可以傳送邀請給一位或多位朋友；而且邀請一律帶有加入遊戲的呼籲字句。收到邀請的用戶可以是現有玩家，也可以是新玩家。

遊戲邀請可以用來吸引新玩家或再次接觸現有玩家。有 2 種情況可以傳送邀請：

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

以明確指示 action_type 及 object_id 的方式，使用 iOS SDK 傳送邀請給特定接收者：

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]

接收者接受邀請後，該邀請並不會自動刪除。刪除工作需由您的遊戲完成。常見做法是於遊戲啟動時，從 Graph API 讀取該用戶尚未確認的邀請清單，並於處理後將邀請逐個刪除。

若接收者在流動平台上接受邀請，則會產生與該應用程式的深層連結，這樣就會在應用程式載入的過程中產生額外的參數，亦即邀請編號。流動平台同樣必須負責處理接受及清除邀請的操作，我們建議在遊戲啟動時檢查並清除待處理的邀請。

讀取邀請

每個傳送邀請都有不重複的邀請物件編號，該編號正好代表邀請物件。此邀請物件編號可以與接收者用戶編號串連，以建立特定的邀請實例。這代表了一個傳送給特定接收者的邀請實例。

例如，傳送邀請時，遊戲邀請對話框的回應會如下所示：

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

若您透過 Graph 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]

刪除邀請

接收者接受遊戲邀請後，此類邀請並不會自動刪除。邀請被接受後，刪除工作需由開發人員完成。邀請被接受後，您必須代表玩家刪除邀請。

您可以透過以下方式刪除邀請：

Graph 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 獎勵傳送者。若是多位朋友邀請了同一位玩家，您可以選擇獎勵第一位傳送者或所有傳送者。

可邀請的朋友 API

本地化

為幫助您向全球受眾帶來優質的用戶體驗，Facebook 支援為 requests 提供本地化服務。在您翻譯邀請內容之前，事先了解不同的邀請類型及其顯示方式非常重要。邀請可能會以標準方式顯示（例如:「Anita 向你傳送了一個邀請」），或者指定了特定的動作／物件配對（例如：「Anita 向你請求一條生命」或「Anita 向你傳送了一個炸彈」）。另外，系統亦有提供回合制邀請，讓玩家知道自己與朋友在對戰中的遊玩回合。以上所有範例只向已驗證遊戲的玩家顯示。若接收者尚未安裝遊戲，則這些要求就會以邀請的形式出現，例如「Anita 邀請你玩 Friend Smash！」。讓我們來看看應該怎麼翻譯比較好。

翻譯邀請

邀請文字會由 Facebook 自動翻譯，這是開發人員無法控制的部分。我們會將邀請翻譯為接收者的使用語言。

英文版邀請通知

泰文版邀請通知

請注意，在上方的範例中，文字「邀請你玩」(invited you to play) 自動翻譯為其他語言，在這個範例中即為泰文。應用程式名稱及說明可以在應用程式設定的「本地化」部分中翻譯，如下圖所示的黃色方框（「顯示名稱」、「說明」）。

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

邀請也會在應用程式中心顯示。在應用程式中心內，系統會顯示邀請的「訊息」。這段訊息可由開發人員翻譯。請看下列範例，英文訊息為「Can I have a life to help me through the next level?」，泰文訊息為「ช่วยส่งตัวเพิ่มให้หน่อย ต้องใช้ไปเลเวลหน้า」。這時，邀請的主要文字「Anita 向你傳送了一個邀請」不會在應用程式中心顯示。

應用程式中心內的英文版邀請

應用程式中心內的泰文版邀請

翻譯訊息內容

訊息會在邀請對話框觸發時以參數形式傳遞，因此您可以在觸發對話框之前自行翻譯，並將翻譯好的字串作為訊息傳遞出去。如果您想動態變更翻譯，您應該在觸發對話框前操作。您可以自行決定顯示訊息所用的語言，因為您所選的文字會在傳送者的邀請預覽及接收者收到的邀請內容中顯示。

很多開發人員都會偵測傳送者的當地語言，然後使用這個資訊來決定以何種語言傳送訊息。他們假設，在絕大多數情況下，傳送者及接收者會使用相同的語言。根據上方的範例，您可以查看傳送者的當地語言；如果是泰文的話，您就可以直接以泰文傳送字串作為訊息，如下所示：

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

最佳操作實例

在邀請中附加資料

如同我們先前在對話框參數部分所述，您可以在邀請中附加多達 255 個字元的其他資料一併傳送。您可以利用這個機制傳送與要求相關的資訊，或者附加日後用來查詢伺服器相關資訊的識別碼。

例如，在 Facebook 遊戲專案範例 Friend Smash 中，玩家會輪流比賽，並以「擊碎」朋友次數最多者為勝方。當某位玩家傳送挑戰邀請給另一位玩家時，資料參數即會儲存挑戰玩家的最新分數。然後，遊戲可以擷取這個分數值並提供給接受挑戰的玩家，以此分數作為下一場比賽的目標分數。

篩選邀請

建立自訂朋友複選工具或選擇傳送要求的對象時，您可以考慮提供篩選條件幫助玩家選擇合適的接收者。

使用遊戲邀請對話框來邀請別人時，app_non_users 是很常用的篩選條件。這個篩選條件可以避免遊戲邀請對話框顯示之前已經玩過您遊戲的玩家。其他適用的篩選條件包括最近互動過的玩家，或者玩過其他由您控制的類似遊戲的玩家。若要查看完整的篩選條件清單，請參閱遊戲邀請對話框—參數參考文件。

建立互動機制

建立互動機制可以讓玩家拜訪遊戲內的朋友，或與朋友直接互動。例如，如果遊戲支援鄰居概念，每當玩家拜訪鄰居的遊戲環境時，就可以提供額外的生命值作為獎勵；若玩家的基地遭到攻擊，讓玩家的朋友一起協助修復。玩家通常會覺得幫助朋友提升遊戲進度很有成就感，若向他們提供這樣的機會，您就可以營造更好的社交體驗，並吸引更多玩家。

讓玩家看到物件的價值

提供玩家非常重視的內容，例如，幫助他們強化遊戲及社群體驗。

以情境分類玩家並提供邀請

評估您的玩家，並按遊戲的邏輯將他們分成不同的遊戲目標族群（例如新玩家、喜歡製作物品的玩家、擁有很多朋友的玩家、互動程度高的玩家等等）。考慮玩家在自身所處等級看重哪些項目，然後為每個目標族群提供特定物品。