小遊戲快速入門

設定應用

即便您已有託管到 Facebook.com 的網頁遊戲，或託管到移動應用商店的移動遊戲，也需要為自己的小遊戲建立一款新應用。您無法使用與其他應用相同的 Facebook 應用編號製作一款小遊戲。

 

將類別設定為 “遊戲”

前往應用皮膚的基本設定版塊，確保將類別設定為遊戲。儲存更改。

 

為應用新增管理員、開發者和測試員

Facebook 正在逐步面向更廣泛的受眾推廣小遊戲，您的遊戲目前可能無法對所有使用者開放。要確保遊戲的所有發開者和測試員擁有訪問許可權，請在應用皮膚的使用者身份選項卡中將他們新增為應用的管理員、開發者或測試員（請參見下方截圖）。詳細瞭解使用者身份。

 

在應用皮膚中啟用小遊戲功能

請注意：請勿向針對 iOS 、 Android 或 Web 環境配置的原有 Facebook 應用新增小遊戲。為小遊戲建立的 Facebook 應用編號不適用於其他平臺。

 

新建 Facebook 應用

要為應用啟用 * 小遊戲功能，點選導航選單底部的 + 新增商品按鈕。 這一操作將開啟應用中的可用產品列表。在列表中找到小遊戲，並點選開始按鈕。這一操作將為選單新增一個小遊戲版塊。確保開啟在小遊戲平臺上架開關。儲存更改，然後繼續。

 

SDK 第一步

匯入

現在您已設定好應用，需要開始建立遊戲客戶端。 遊戲客戶端根目錄下需要有一個 index.html 檔案。請首先從此檔案匯入小遊戲 SDK 。

 

<script src="

初始化

我們的 SDK 廣泛使用 Promises 來實現非同步功能。您只能在 FBInstant.initializeAsync() 解析完成後與載入的使用者介面互動。

 

FBInstant.initializeAsync()

  .then(function() {        

     // Start loading game assets here

  });

遊戲客戶端不會一次性下載所有捆綁包（ .zip 檔案），而是會搜尋配置根檔案 (fbapp-config.json) 和主檔案 (index.html) 。之後，它將開始執行主檔案中所含的邏輯，並開始從此處下載資產。開發者可以全權控制資產載入的順序和時間。

 

在開始下載初始化遊戲所需的資產後，您需要將載入進度告知 SDK ，以便我們向玩家展示載入進度環。

 

var images = ['sprite1', 'sprite2', ...];

for (var i=0; i < images.length; i++) {

  var assetName = images[i];  

  var progress = ((i+1)/images.length) * 100;  

  game.load.image(assetName);

 

  // Informs the SDK of loading progress

  FBInstant.setLoadingProgress(progress);

}

 

// Once all assets are loaded, tells the SDK

// to end loading view and start the game

FBInstant.startGameAsync()

  .then(function() {

    // Retrieving context and player information can only be done

    // once startGameAsync() resolves

    var contextId = FBInstant.context.getID();

    var contextType = FBInstant.context.getType();

 

    var playerName = FBInstant.player.getName();

    var playerPic = FBInstant.player.getPhoto();

    var playerId = FBInstant.player.getID();

 

    // Once startGameAsync() resolves it also means the loading view has

    // been removed and the user can see the game viewport

 

    game.start();

  });

如需詳細瞭解 initializeAsync() 、 setLoadingProgress() 和 startGameAsync() 方法，請參閱 SDK 參考文件。

 

測試和上傳

小遊戲內容在 Facebook 基礎設施上託管，因此，無需自行託管遊戲內容或使用第三方服務。在準備好遊戲進行測試後，將所有遊戲檔案打包為一個 .zip 檔案。請注意， index.html 檔案應位於此存檔的根資料夾中，而不應位於任何子資料夾中。

 

要上傳 .zip 檔案，請點選應用皮膚中的虛擬主機選項卡。從該選項卡的下拉選單中選擇“小遊戲”，然後單擊 + 上傳版本，即可將 .zip 檔案上傳到 Facebook 的託管服務中。

 

之後，構建版本會處理檔案，僅需數秒時間。狀態更改為 “待命”時，單擊“★”按鈕將構建版本推送到生產。

 

 

之後，您可以在移動裝置中測試構建版本。現在，在 Messenger 內的遊戲列表中，您可以在“開發中”版塊下看見已釋出的構建版本。為了加快開發流程，您可以參考此指南，瞭解如何透過圖譜 API 從命令列上傳構建版本，或者如何直接從開發伺服器進行測試：測試、釋出和分享小遊戲

 

遊戲環境更新

我們已經介紹過使用小遊戲 SDK 的基本知識，現在來看看如何讓您的遊戲與遊戲環境互動。

 

我們用遊戲環境一詞來定義可以玩遊戲的任何環境。更多情況下，遊戲環境是指 Messenger 對話，但如果遊戲不是在 Messenger 中玩，遊戲環境也可以指其他各種位置，例如 Facebook 帖子或小組。

 

以下示例說明了如何傳送遊戲環境更新及其在 Messenger 對話中的展示效果。

 

第 1 步：在配置檔案中宣告模板

為了宣告自定義更新，您需要建立名為 fbapp-config.json 的配置檔案，並將其放在捆綁包的根目錄中，與 index.html 檔案放在一起。如需詳細瞭解受支援的配置，請參閱捆綁包配置部分。 在本示例中，檔案內容應該如下所示：

 

{

  "instant_games": {

    "platform_version": "RICH_GAMEPLAY",

    "custom_update_templates": {

      "play_turn": {

        "example": "Edgar played their move"

      }

    }

  }

}

透過自定義更新模板配置，我們可以為每個特定的自定義更新分配一個編號，從而更好地進行分析。您必須為所有遊戲分配模板編號。

 

第 2 步：使用 updateAsync 傳送自定義更新

在配置檔案中宣告模板後，便可將模板用於填充 FBInstant.updateAsync 中的必填 template 欄位。以下示例說明井字棋遊戲如何利用呼叫通知對手輪到他們出棋。您可以在右側看到訊息的展示效果。

 

  // This will post a custom update. If the game is played in a messenger

// chat thread, this will post a message into the thread with the specified

// image and text message. And when people launch the game from this

// message, those game sessions will be able to access the specified blob

// of data through FBInstant.getEntryPointData().

FBInstant.updateAsync({

  action: 'CUSTOM',

  cta: 'Play',

  image: base64Picture,

  text: {

    default: 'Edgar played their move',

    localizations: {

      en_US: 'Edgar played their move',

      es_LA: '\u00A1Edgar jug\u00F3 su jugada!'

    }

  }

  template: 'play_turn',

  data: { myReplayData: '...' },

  strategy: 'IMMEDIATE',

  notification: 'NO_PUSH'

}).then(function() {

  // closes the game after the update is posted.

  FBInstant.quit();

});

 

 

有關自定義遊戲環境更新的更多資訊，請參閱我們的小遊戲 SDK 參考文件。

 

如需檢視相關最佳實踐指南，瞭解何時向其他玩家傳送訊息、何時向他們傳送通知以及最好在遊戲環境更新中新增哪些內容，請參閱我們的最佳實踐部分。

 

請注意，遊戲環境更新不會傳送到 Messenger 以外的地方。透過使用 context.getType() 方法和檢測 THREAD 來定製遊戲體驗非常有用。您可以使用 context.switchAsync 、 context.chooseAsync 或 context.createAsync 切換到更為合適的遊戲環境。

 

（可選）設定遊戲智慧助手，再次吸引玩家

小遊戲的一項重要功能是能附加 Messenger 平臺智慧助手。這項功能雖為選擇性配置，卻為遊戲提供了一個強有力的再參與渠道。以下指南說明了如何建立和設定遊戲智慧助手。

 

第 1 步：建立主頁

如需建立遊戲智慧助手，您首先需要建立 Facebook 主頁。主頁要正確地與小遊戲關聯，需要具備一些特殊的屬性：

 

主頁類別需要是應用主頁

主頁名稱需要包含應用名稱。

主頁不能與其他應用關聯。

您可以前往 “應用皮膚”，在小遊戲產品的應用主頁版塊建立滿足這些特殊條件的主頁。 在執行下一步操作前，請確保應用主頁版塊如右圖所示：

 

注意：如果小遊戲未與上述型別的主頁正確關聯，智慧助手將不會收到 messaging_game_plays 事件

 

第 2 步：啟用智慧助手

建立主頁後，您需要確保響應其訊息 webhooks 。 Webhooks 是在向您的主頁傳送訊息事件時，我們向您的後端傳送的 HTTP 呼叫。之後，您的伺服器的邏輯將決定如何正確地響應每個事件（如果響應適用）。 如需將伺服器的端點與主頁事件相關聯，請按照 Messenger 平臺快速入門教程中的說明為主頁啟用智慧助手。下表介紹了將智慧助手與小遊戲關聯所需的 webhooks 和許可權：

 

部分 值

主頁事件

 

messages 和 messaging_game_plays

 

許可權

 

pages_messaging

 

小遊戲智慧助手僅可使用標準訊息和 GAME_EVENT 訊息標籤，不能使用 pages_messaging_subscriptions 。

 

如果您的智慧助手具有需要用到訂閱訊息或客戶匹配的其他功能，您應建立單獨的應用並重新申請 Messenger 平臺許可權。

 

第 3 步：響應 messaging_game_plays webhooks

正確配置智慧助手後，您的伺服器端應用程式將開始在玩家每次關閉小遊戲時接收 messaging_game_plays webhooks 。下面是伺服器端應用程式檢測到並響應一個 webhook 的示例。

 

if (event.game_play) {

  var senderId = event.sender.id; // Messenger sender id

  var playerId = event.game_play.player_id; // Instant Games player id

  var contextId = event.game_play.context_id;

  var payload = event.game_play.payload;

  var playerWon = payload['playerWon'];

  if (playerWon) {

    sendMessage(

      senderId,

      contextId,

      'Congratulations on your victory!',

      'Play Again'

    );

 

  } else {

    sendMessage(

      senderId,

      contextId,

      'Better luck next time!',

      'Rematch!'

    );

  }

}

您可以參閱 Messenger 平臺文件，詳細瞭解 webhook ：“玩遊戲” Webhook 文件。

 

第 4 步：吸引玩家重回遊戲

以下是如何使用圖譜 API 向玩家傳送 game_play 按鈕的示例。

 

curl "

   -X POST

   -H "Content-Type: application/json"

   -d '{

  "messaging_type": "UPDATE",

  "recipient": {

    "id": "<RECIPIENT_ID>"

  },

  "message": {

    "attachment": {

      "type": "template",

      "payload": {

        "template_type": "generic",

        "elements": [

          {

            "title": "It has been a while since your last game. Time to get back",

            "buttons": [

              {

                "type": "game_play",

                "title": "Play Tic-Tac-Toe.",

                "payload": "{}",

                "game_metadata": {

                  "context_id": "<CONTEXT_ID>"

                }

              }

            ]

          }

        ]

      }

    }

  }

}'

 

您可以參閱 Messenger 平臺文件，詳細瞭解此按鈕：“玩遊戲”按鈕文件。

 

第 5 步：遵循我們的指南和政策

釋出至生產階段後，您的遊戲智慧助手應進入 Messenger 平臺提交流程。提交智慧助手之前，請確保遵守下面的最佳實踐：

 

建議：

向玩家提供相關、及時且有價值的更新。如需獲取更多資訊，請訪問我們的最佳實踐版塊。

 

給予使用者掌控權（例如：讓使用者確認他們是否想要接收通知以及以接收的頻率）。

 

對玩遊戲按鈕使用入口點資料，以環境相關的方式載入遊戲。

 

為智慧助手設定與遊戲相同的名稱。

 

利用社交更新，如回合提醒、比賽結果、限時獎勵和挑戰。

 

確保為玩家提供適當的獎勵刺激，促使他們透過智慧助手訊息開啟遊戲。為此，您可使用訊息負載為玩家提供有價值的遊戲內獎勵。一般來說，如果智慧助手訊息開啟的是遊戲的開始頁面，這條訊息便沒有什麼價值。

 

使用固定選單提供常見操作，如啟動遊戲。

 

設定預設操作，在自定義更新中使用 game_play ，以便整個圖片都能將使用者帶入遊戲中。

 

透過智慧助手公佈新功能或內容。

 

針對每位使用者最佳化每天的訊息傳送時段，考慮使用者所在的時區。

 

借鑑 Messenger 智慧助手的通用最佳實踐。

 

請勿：

 

在玩家關閉遊戲後立即傳送訊息。

 

 

傳送沒有任何背景資訊的訊息再次吸引玩家（例如： “立即回到遊戲中！”）。建議首選包含豐富背景資訊的訊息來重新吸引玩家（例如：“你的偵查員為你帶回了更多資訊”）

 

 

使用其他 Facebook 使用者的口吻，或誤導玩家以為他們好友在與他們溝通。

 

 

在使用者屢次不想加入遊戲的情況下繼續向他們傳送智慧助手訊息。這種情況將適用政策限制，並阻止您傳送訊息。當前的限制為，自最後一次遊戲會話結束後 10 天最多可傳送 5 條訊息。如需詳細瞭解，請參閱我們的開放平臺政策文件中的第 9.4 條

 

 

將 messaging_type 設定為 RESPONSE 或 UPDATE 以外的其他任何值

 

 

連結至任何應用商店。

為方便大家群策群力， 我 們 建立了一個 Facebook Instant Game   交流群： 814298516 。 歡迎同 學 們加入 交流開發和運營經驗。