facebook instant game 釋出指南-小遊戲 SDK

本部分包含關於小遊戲 JavaScript SDK 的 API 參考文件。 如果您想開始構建新遊戲，建議始終使用我們的最新版 SDK。請點選下方的按鈕，參閱關於最新版 SDK 的參考文件：

版本 6.2（參閱參考文件）

（新增）關聯玩家分數記錄推出新的Leaderboard.getConnectedPlayerEntriesAsync()API， 可通過排行榜獲取當前玩家的 關聯玩家的分數記錄。

版本 6.1（參閱參考文件）

智慧助手訂閱 API藉助智慧助手訂閱 API， 遊戲可以讓玩家訂閱遊戲的 Messenger 智慧助手（如果玩家未訂閱）。

[僅限 Android] 主螢幕快捷方式 API藉助主螢幕快捷方式 API，開發者可以在遊戲內向玩家展示 儲存對話方塊，方便他們將遊戲儲存到主螢幕。

匹配 API（更新）此版本還包括匹配 API 的更新。我們 新增了一個額外的引數，用於指定您是希望遊戲在玩家匹配後就切換到 新建立的環境中， 還是等到玩家在 Toast 中點選“玩遊戲”按鈕之後才切換。

版本 6.0（參閱參考文件）

排行榜此版本全新推出排行榜 API！提供一套強大的 API， 使得遊戲可獲取排行榜、查詢得分 情況和設定新分數（支援分數所帶的 任意後設資料），並可向 Messenger 對話推送結構化的排行榜 更新訊息。

遊戲內切換我們還針對遊戲內交叉推廣引入了一個新 API。它目前 處於封測階段，如果您有興趣在自己的遊戲中幫忙 測試遊戲內切換 API 的整合效果，請聯絡 您的合作伙伴經理！遊戲內切換 API 可在 iOS 和 Android 裝置的 Facebook v159+ 和 Facebook Messenger v153+ 使用。

版本 5.1（參閱參考文件）

應用內購買 API增加了小遊戲適用的應用內購買 API。遊戲可藉此獲取目錄和 玩家購買情況，併購買和使用物品。目前處於封測階段。

配對 API藉助此 API，遊戲可以將當前玩家與其他感興趣玩家的遊戲環境 進行匹配。目前處於封測階段。

版本 5.0（參閱參考文件）

廣告 API兩款全新的 API 可方便投放插屏廣告和獎勵式視訊廣告。要求 配置遊戲以便在小遊戲中投放廣告。

Player StatsAPI，用於設定、獲取並自動增加與玩家相關的 整數統計資料。輔以捆綁包配置的新增內容， 可為玩家統計資料配置後設資料， 通過 Facebook 平臺級整合顯示統計資料。

getEntryPointAsyncAPI，獲取啟動遊戲的入口點。

Custom Update Dev Localization自定義更新 API 的增補， 讓開發者能夠提供更新內容的本地化版本。

重大更改將 CLIENT_REQUIRES_UPDATE 更名為 CLIENT_UNSUPPORTED_OPERATION

版本 4.1（參閱參考文件）

FBInstant.player.getSignedPlayerInfoAsync()提供有關當前玩家資訊的負載， 使用遊戲的應用金鑰簽名，以驗證所有 資訊均來自於 Facebook 且準確無誤。

FBInstant.context.getPlayersAsync()提供所有加入當前遊戲環境的活躍玩家 的列表。目前，受支援的常規玩家資訊包括 玩家編號、姓名和照片網址。

FBInstant.context.isSizeBetween()允許遊戲檢查加入當前遊戲環境的人數 （包括非玩家）是否在一定範圍內。在一個遊戲環境中僅允許對每個會話 進行一次檢查，後續請求只會返回最初的 結果。

環境篩選條件我們已為 FBInstant.context.chooseAsync() 新增可選的篩選條件引數，這讓遊戲可以按照環境推薦請求使用篩選條件， 包括設定環境規模範圍、將篩選結果限制在環境中 未玩過遊戲的新玩家上，以及為“當前挑戰”新增 額外部分。此功能正面向我們的客戶逐步推廣， 以下是具體的時間安排：

iOS - Messenger v133（8 月 30 日）

Android - Messenger v135（9 月 11 日）

Web - 9 月初

版本 4.0（參閱參考文件）

（更新）ConnectedPlayer更新了 Connected Player 物件。該物件將不再有 “id”屬性，而是提供下列屬性：

.id — 玩家的編號

.name — 玩家的全名

.photo — 玩家公開的頭像網址

（更新）Platform我們正推出一種新的平臺型別 —“MOBILE_WEB”。雖然移動 網頁播放器現在尚未公開可用，但在釋出後它將使用 此平臺型別。遊戲應確保針對此平臺型別設定正確的控制元件， 為所有玩家提供 最佳體驗。

（新增）Custom Update Templates現在，呼叫 FBInstant.updateAsync() 以傳送自定義更新時，必須 在“template”欄位填充要傳送的自定義更新型別的 ID， 具體資訊請參閱遊戲的捆綁包配置檔案  (https://developers.facebook.com/docs/games/instant-games/bundle-config)。

（更新）Context Choose Options— 進行中我們正在為 FBInstant.chooseAsync() 新增可選的篩選條件， 這些篩選條件會影響我們向玩家推薦的一系列遊戲環境。 涉及這一更新的客戶端實施仍在穩步推進，但開發者現在即可 在遊戲中整合這些選項。 最初支援的選項有：

minSize — 在推薦的遊戲環境中，遊戲支援的最少 玩家數量

maxSize — 在推薦的遊戲環境中，遊戲支援的最多 玩家數量

filters — 一組篩選條件。支援的第一個篩選條件 是 NEW_CONTEXT_ONLY，此篩選條件會嘗試僅面向之前未玩過遊戲的使用者 推薦遊戲環境。

版本 3.2（參閱參考文件）

FBInstant.getSupportedAPIs()提供客戶端支援的 SDK API 的列表。 僅適用於遊戲可用的顯示功能。

FBInstant.player.flushDataAsync()立即將佇列中的任何更改重新整理到玩家資料中。玩家資料 會正常保留在後端，所以這種方法可便於清楚地瞭解 是否存在更改。

FBInstant.context.createAsync(playerID)允許遊戲指定一個玩家，且活躍玩家應 通過這個玩家進入遊戲環境。指定的玩家必須是對應活躍玩家的 關聯玩家。

自定義更新策略：IMMEDIATE CLEAR清除任何待處理的更新（例如通過“LAST”策略設定的更新）。 這主要適用於以下情況：遊戲需要傳送重要更新，但為了優先處理新更新， 應先清除某些現有的 重要性較低的待處理更新。

版本 3.1（參閱參考文件）

（更新）FBInstant.updateAsync()現在我們接受 CustomUpdatePayload 中的“notification”引數， 允許開發者明確設定更新是否應該 觸發推送通知。請參閱關於 updateAsync 的 文件瞭解詳細資訊。

版本 3.0（參閱參考文件）

（刪除）FBInstant.game.setScore()現在，開發者能夠利用我們極具靈活性的開放平臺， 在他們自己的後端保留可自定義的排行榜。

（刪除）FBInstant.takeScreenshotAsync()和FBInstant.sendScreenshotAsync()在極具靈活性的新版開放平臺中，分享內容不再侷限於截圖， 使用者可以分享任何圖片。替換為FBInstant.shareAsync()。

（刪除）FBInstant.endGameAsync()替換為FBInstant.quit()，從而將控制權交回給玩家。

（刪除）FBInstant.abort()替換為FBInstant.quit()，從而能夠處理任何退出條件。

（新增）FBInstant.quit()， 將控制權交回 Facebook Messenger 使用者介面。用於遊戲應該退出 或處於不可恢復的錯誤狀態時。

（新增）FBInstant.updateAsync()在 Messenger 對話中傳送完整的可自定義訊息。

（新增）FBInstant.getEntryPointData()允許隨更新訊息一同傳送通用資料塊

（新增）FBInstant.onPause()方便開發者設定處理程式，用於處理遊戲中斷的情況 （例如：切換應用、接打電話）

（新增）FBInstant.player.getConnectedPlayersAsync()檢索當前玩家的 Facebook 好友或 Messenger 聯絡人的 玩家編號。只會返回 也在玩小遊戲的玩家。

（新增）FBInstant.context.chooseAsync()為使用者呈現當前遊戲環境的更改介面 （例如：更改 Messenger 對話）。

（新增）FBInstant.context.switchAsync()切換為任一環境 ID（例如：根據已知的環境 ID 切換至特定的  Messenger 對話）。

（新增）FBInstant.shareAsync()為使用者顯示分享對話方塊，方便他們與好友分享遊戲內容。

（新增）FBInstant.setSessionData()方便開發者在特定的遊戲環境中為當前的會話 設定自定義負載。可用於填充智慧助手 Webhook。

版本 2.1（參閱參考文件）

（新增）FBInstant.logEvent()將事件記錄到 Facebook 分析中

（新增）FBInstant.context.getType()返回當前所玩遊戲的環境型別。

版本 2.0（參閱參考文件）

（重大更改）公共 API 屬性更新為函式我們已將所有公共 API 屬性（如FBInstant.locale）更新為函式（如FBInstant.getLocale()）。這一更改可讓 SDK 介面在未來具備向後相容性。這些函式都是同步的，並會立即返回響應。

（新增）FBInstant.player.getName()：FBInstant.player.getName會返回當前玩家的本地化顯示名稱。

（新增）FBInstant.player.getPhoto()：FBInstant.player.getPhoto會返回當前玩家的頭像網址。

（更新）FBInstant.takeScreenshotAsync()：以前是FBInstant.takeScreenshot，現更名為FBInstant.takeScreenshotAsync，並會返回 Promise。如果我們未能成功截圖，那麼這個 Promise 將被拒絕。

（更新）FBInstant.sendScreenshotAsync()：以前是FBInstant.sendScreenshot，現更名為FBInstant.sendScreenshotAsync，並會返回 Promise。如果圖片無效，那麼這個 Promise 將被拒絕。

版本 1.1（參閱參考文件）

（新增）遊戲環境識別符號FBInstant.context.id提供玩家開始遊戲比賽時所在的環境的資訊。這是 Messenger 對話或動態訊息中的動態的唯一識別符號，具體視開始遊戲的位置而定。

（新增）鍵值儲存FBInstant.player.getDataAsync和FBInstant.player.setDataAsync讓您能夠在 Facebook 後端儲存玩家提供的資訊。

（更新）FBInstant.locale：現在會返回使用者實際使用的語言環境，而非預設的測試值'en_US'

（更新）FBInstant.player.id：現來自我們的後端系統，所以可用於跨所有應用和裝置識別同一使用者。

版本 1.0（參閱參考文件）

方法重新命名：之前，我們為特定呼叫指定了名稱空間，現在我們在方法名稱中新增了這些呼叫的域名。 我們還重新命名了一些方法，以提高明確性。重新命名的方法如下：

FBInstant.loading.setProgress()現在為FBInstant.setLoadingProgress()

FBInstant.loading.complete()現在為FBInstant.startGameAsync()

FBInstant.game.setScore()現在為FBInstant.setScore()

FBInstant.game.asyncYieldControl()現在為FBInstant.endGameAsync()

FBInstant.media.takeScreenshot()現在為FBInstant.takeScreenshot()

FBInstant.media.sendPicture()現在為FBInstant.sendScreenshot()

FBInstant.system.abort()現在為FBInstant.abort()

（新增）Initialization：新增方法FBInstant.initializeAsync()，此方法應返回一個 Promise。此 Promise 履行後，會為全域性物件設定正確的資訊。 除此之外，系統僅在玩家實際開始玩遊戲時解析FBInstant.startGameAsync()返回的 Promise。 因此使用這一 API 時，遊戲本身必須有“輕觸開始”按鈕

（新增）平臺資訊：新增FBInstant.platform屬性，初始化後將填充為以下 3 個值中的一個：'iOS'、'android'或'web'

（新增）語言資訊：新增FBInstant.locale屬性，初始化後將填充為使用者的語言程式碼。

（新增）玩家 ID 資訊：新增FBInstant.player.id屬性，初始化後將填充為玩家的匿名 ID。

刪除未實施的方法：之前被標記為[未實施]的所有方法均已刪除。這些方法會在實施後重新新增。

在 SDK 檔名稱中新增 API 版本資訊：此檔案現在可通過fbinstant.1.0.js獲取。 新發布檔案的名稱將始終包含 API 的版本資訊。fbinstant.js將保持為當前版本，不會升級或更改。 最新版本可隨時通過fbinstant.latest.js獲得，但建議不要直接指出對應的路徑，因為以後可能在這個路徑下實施重大更改。

另外我建立了一個 Facebook Instant Game   交流QQ群：814298516

歡迎同行們加入討論技術