Facebook 遊戲開發更新文件 API 參考文件 v5.0
更新日誌 1.廣告 API 兩款全新的 API 可方便投放插屏廣告和獎勵式視訊廣告。要求 配置遊戲以便在小遊戲中投放廣告。 2.Player Stats API，用於設定、獲取並自動增加與玩家相關的 整數統計資料。輔以捆綁包配置的新增內容， 可為玩家統計資料配置後設資料， 通過 Facebook 平臺級整合顯示統計資料。 3.getEntryPointAsync API，獲取啟動遊戲的入口點。 4.Custom Update Dev Localization 自定義更新 API 的增補， 讓開發者能夠提供更新內容的本地化版本。 5.重大更改將 CLIENT_REQUIRES_UPDATE 更名為 CLIENT_UNSUPPORTED_OPERATION
FBInstant 小遊戲 SDK 的頂級名稱空間。
player 包含與當前玩家相關的功能和屬性。
getID( ) 玩家的唯一標識。Facebook 使用者的玩家編號 將保持不變，且僅限於特定遊戲範圍。這意味著 同一個使用者在不同的遊戲中有不同的玩家編號。 僅當 FBInstant.initializeAsync() 被解析後才應呼叫此 函式。 示例 // This function should be called after FBInstant.initializeAsync()// resolves.var playerID = FBInstant.player.getID(); 返回字串？ 玩家的唯一標識。
getSignedPlayerInfoAsync( ) 獲取玩家的唯一標識和簽名，簽名用於驗證標識確實 來自 Facebook，且沒有被篡改。 僅當 FBInstant.initializeAsync() 被解析後才應呼叫此 函式。 引數 requestPayload字串？ 開發者指定的包含於 已簽名響應中的負載。 示例 // This function should be called after FBInstant.initializeAsync()// resolves.FBInstant.player.getSignedPlayerInfoAsync('my_metadata') .then(function (result) { // The verification of the ID and signature should happen on server side. SendToMyServer( result.getPlayerID(), // same value as FBInstant.player.getID() result.getSignature(), 'GAIN_COINS', 100); }); 丟擲 INVALID_PARAM 丟擲 NETWORK_FAILURE 丟擲 CLIENT_UNSUPPORTED_OPERATION 返回 Promise 以 #signedplayerinfo 物件解析的 promise。
getName( ) 經本地化顯示的玩家姓名。僅當 FBInstant.startGameAsync() 被解析後 才應呼叫此函式。 示例 // This function should be called after FBInstant.startGameAsync()// resolves.var playerName = FBInstant.player.getName(); 返回字串？ 經本地化顯示的玩家姓名。
getPhoto( ) 玩家公開頭像的網址。此照片始終為正方形， 尺寸至少為 200x200 畫素。在遊戲中顯示時， 確切的尺寸可能會有所變化。建議 始終在顯示之前將圖片調整為需要的尺寸。 對應的值將始終為 null，直至 FBInstant.startGameAsync() 被解析。 警告：由於使用 CORS 機制，在遊戲 Canvas 中使用這些照片會導致照片 損壞，這有礙於提取 Canvas 資料。 為防止出現這種情況，應將您使用的圖片的 cross-origin 屬性設定為 “anonymous”。 示例 var playerImage = new Image(); playerImage.crossOrigin = 'anonymous';// This function should be called after FBInstant.startGameAsync()// resolves. playerImage.src = FBInstant.player.getPhoto(); 返回字串？ 玩家公開頭像的網址。
getDataAsync( ) 從指定的雲端儲存中檢索當前玩家的資料。 引數 keys陣列<字串> 唯一鍵陣列，資料檢索將針對這些鍵展開。 示例 FBInstant.player .getDataAsync(['achievements', 'currentLife']) .then(function(data) { console.log('data is loaded'); var achievements = data['achievements']; var currentLife = data['currentLife']; }); 丟擲 INVALID_PARAM 丟擲 NETWORK_FAILURE 丟擲 CLIENT_UNSUPPORTED_OPERATION 返回 Promise<物件> 此 promise 將在獲得 包含下列資訊的物件時被解析：輸入陣列中指定的每個鍵的 當前鍵值對（如存在）。
setDataAsync( ) 設定要儲存到指定雲端儲存的當前玩家 的資料。對於每個獨立玩家，遊戲最多可儲存 1MB 的資料。 引數 data物件 此物件包含 應該儲存到雲端儲存的一組鍵值對。物件必須僅包含 可序列化的值 — 任何不可序列化的值都會導致 整個修改被拒絕。 示例 FBInstant.player .setDataAsync({ achievements: ['medal1', 'medal2', 'medal3'], currentLife: 300, }) .then(function() { console.log('data is set'); }); 丟擲 INVALID_PARAM 丟擲 NETWORK_FAILURE 丟擲 PENDING_REQUEST 丟擲 CLIENT_UNSUPPORTED_OPERATION 返回 Promise 此 promise 將在輸入值設定時被解析。 注意：promise 被解析並不一定意味著輸入 已被儲存，而是這意味著相關資料有效 並已安排要被儲存。這還能保證設定的所有值 現在可在 player.getDataAsync 中使用。
flushDataAsync( ) 立即將玩家資料的任何更改重新整理到指定的 雲端儲存中。此函式的呼叫成本較高， 應主要用於需要立即儲存並告知遊戲的 重要更改。非重要更改應依賴於開放平臺在後臺 進行儲存。 注意：當此函式的結果待定時， player.setDataAsync 呼叫將被拒絕。 示例 FBInstant.player .setDataAsync({ achievements: ['medal1', 'medal2', 'medal3'], currentLife: 300, }) .then(FBInstant.player.flushDataAsync) .then(function() { console.log('Data persisted to FB!'); }); 丟擲 INVALID_PARAM 丟擲 NETWORK_FAILURE 丟擲 PENDING_REQUEST 丟擲 CLIENT_UNSUPPORTED_OPERATION 返回 Promise 此 promise 將在更改儲存成功時被解析， 在更改儲存失敗時被拒絕。
getStatsAsync( ) 從指定雲端儲存檢索當前玩家的統計資料。 引數 keys陣列<字串>？ 唯一鍵陣列（可選），針對這些鍵檢索 統計資料。如果呼叫函式時沒有設定此引數，則會提取所有統計資料。 示例 FBInstant.player .getStatsAsync(['level', 'zombiesSlain']) .then(function(stats)) { console.log('stats are loaded'); var level = data['level']; var zombiesSlain = data['zombiesSlain']; }); 丟擲 INVALID_PARAM 丟擲 NETWORK_FAILURE 丟擲 CLIENT_UNSUPPORTED_OPERATION 返回 Promise<物件> 此 promise 將在獲得 包含下列資訊的物件時被解析：輸入陣列中指定的每個鍵的 當前鍵值對（如存在）。
setStatsAsync( ) 設定要儲存到指定雲端儲存的當前玩家 的統計資料。 引數 stats物件 此物件包含應作為統計資料 儲存到雲端儲存的鍵值對，能以各種方式顯示或 使用這些資料以提高玩家參與度。物件必須 僅包含數值，任何非數值會導致整個 修改被拒絕。 示例 FBInstant.player .setStatsAsync({ level: 5, zombiesSlain: 27, }) .then(function() { console.log('data is set'); }); 丟擲 INVALID_PARAM 丟擲 NETWORK_FAILURE 丟擲 PENDING_REQUEST 丟擲 CLIENT_UNSUPPORTED_OPERATION 返回 Promise 此 promise 將在輸入值設定時被解析。 注意：promise 被解析並不一定意味著輸入 已被儲存，而是這意味著相關資料經過驗證 並已安排要被儲存。這還能保證設定的所有值 現在可在 player.getStatsAsync 中使用。
incrementStatsAsync( ) 儲存到指定雲端儲存的當前玩家 的增量統計資料。 引數 increments物件 此物件包含一組鍵值對， 這些鍵值對錶示雲端儲存中每個統計資料的增量是多少。物件必須 僅包含數值，任何非數值會導致整個 修改被拒絕。 示例 FBInstant.player .incrementStatsAsync({ level: 1, zombiesSlain: 17, rank: -1, }) .then(function(stats)) { console.log('increments have been made! New values'); var level = data['level']; var zombiesSlain = data['zombiesSlain']; }); 丟擲 INVALID_PARAM 丟擲 NETWORK_FAILURE 丟擲 PENDING_REQUEST 丟擲 CLIENT_UNSUPPORTED_OPERATION 返回 Promise<物件> 此 promise 將在獲得包含下列資訊的物件時被解析：輸入字典中指定的每個鍵 的更新鍵值對。 注意：解析 promise 並不一定意味著更改 已被儲存，而是意味著 增量有效且已安排要被執行 。這還能保證增加的所有值 現在可在 player.getStatsAsync 中使用。
getConnectedPlayersAsync( ) 提取 ConnectedPlayer 物件的陣列，這些物件包含與當前玩家 關聯的玩家的資訊。 注意：只有當 FBInstant.startGameAsync() 被解析時，此 promise 才會解析。 示例 var connectedPlayers = FBInstant.player.getConnectedPlayersAsync() .then(function(players) { console.log(players.map(function(player) { return { id: player.getID(), name: player.getName(), } })); });// [{id: '123456789', name: 'Paul Atreides'}, {id: '987654321', name: 'Duncan Idaho'}] 丟擲 NETWORK_FAILURE 丟擲 CLIENT_UNSUPPORTED_OPERATION 返回 Promise<陣列> 此 promise 將在 獲得關聯玩家物件列表時被解析。
context 包含與當前遊戲環境相關的功能和屬性。
getID( ) 當前遊戲環境的唯一標識。這表示 玩遊戲的特定環境（例如：特定的 Messenger 對話或 Facebook 帖子）。如果使用者在獨立環境中玩遊戲，則此標識將 為 null。僅當 FBInstant.startGameAsync 被解析後 才應呼叫此函式。 示例 // This function should be called after FBInstant.startGameAsync()// resolves.var contextID = FBInstant.context.getID(); 返回字串？ 當前遊戲環境的唯一標識。
getType( ) 當前遊戲環境的型別。 僅當 FBInstant.startGameAsync 被解析後才應呼叫此函式。 示例 // This function should be called after FBInstant.startGameAsync()// resolves.var contextType = FBInstant.context.getType(); 返回("POST" | "THREAD" | "GROUP" | "SOLO") 當前遊戲環境的型別。
isSizeBetween( ) 此函式用於確定加入當前遊戲環境的玩家 數量是否在給定的最小值和最大值之間（包括最小值和最大值）。僅當其中一個邊界值為 null 時， 才會根據另一個邊界值進行檢查。在特定 的遊戲會話中，此函式始終會返回某 環境內發出的第一個呼叫的最初結果。後續呼叫（無論引數是什麼）將返回 原始查詢的答案，除非遊戲環境發生變化且 查詢結果被重置。 僅當 FBInstant.startGameAsync 被解析後才應呼叫此函式。 如果提供的一個或兩個引數無效，我們沒有適合當前遊戲環境 的玩家數量，或者 API 在 startGameAsync() 解析之前被呼叫， 此引數都會為 null。 引數 minSize數字？ 環境規模查詢的最小邊界值。 minSize數字？ 環境規模查詢的最大邊界值。 maxSize數字？ 示例 console.log(FBInstant.context.isSizeBetween(3, 5)); (Context size = 4)// {answer: true, minSize: 3, maxSize: 5} console.log(FBInstant.context.isSizeBetween(5, 7)); (Context size = 4)// {answer: false, minSize: 5, maxSize: 7} console.log(FBInstant.context.isSizeBetween(2, 10)); (Context size = 3)// {answer: true, minSize: 2, maxSize: 10} console.log(FBInstant.context.isSizeBetween(4, 8)); (Still in same context)// {answer: true, minSize: 2, maxSize: 10} console.log(FBInstant.context.isSizeBetween(3, null)); (Context size = 4)// {answer: true, minSize: 3, maxSize: null} console.log(FBInstant.context.isSizeBetween(null, 3)); (Context size = 4)// {answer: false, minSize: null, maxSize: 3} console.log(FBInstant.context.isSizeBetween("test", 5)); (Context size = 4)// null console.log(FBInstant.context.isSizeBetween(0, 100)); (Context size = null)// null 返回 ContextSizeResponse？
switchAsync( ) 請求切換到指定環境。如果玩家沒有進入該環境的許可權， 或玩家未向遊戲提供進入 該環境的許可權，請求將被拒絕。 promise 將在 遊戲切換到指定環境時被解析。 引數 id字串 目標環境的編號。 示例 console.log(FBInstant.context.getID());// 1122334455FBInstant.context .switchAsync('1234567890') .then(function() { console.log(FBInstant.context.getID()); // 1234567890 }); 丟擲 INVALID_PARAM 丟擲 SAME_CONTEXT 丟擲 NETWORK_FAILURE 丟擲 USER_INPUT 丟擲 PENDING_REQUEST 丟擲 CLIENT_UNSUPPORTED_OPERATION 返回 Promise 此 promise 將在遊戲切換到指定環境時被解析， 在切換失敗時被拒絕。
chooseAsync( ) 為玩家開啟一個環境選擇對話方塊。如果玩家選擇可用的環境， 客戶端將嘗試切換到這個環境， 並在成功時解析。而如果玩家退出選單或 客戶端未能切換到新環境，此函式 將被拒絕。 引數 options物件？ 此物件用於指定應提供 的環境選項。 options.filters陣列？ 適用於環境推薦的一組篩選條件 。 options.maxSize數字？ 在理想情況下，推薦環境應有 的最大玩家數量。 options.minSize數字？ 在理想情況下，推薦環境應有 的最小玩家數量。 示例 console.log(FBInstant.context.getID());// 1122334455FBInstant.context .chooseAsync() .then(function() { console.log(FBInstant.context.getID()); // 1234567890 }); console.log(FBInstant.context.getID());// 1122334455FBInstant.context .chooseAsync({ filters: ['NEW_CONTEXT_ONLY'], minSize: 3, }) .then(function() { console.log(FBInstant.context.getID()); // 1234567890 }); 丟擲 INVALID_PARAM 丟擲 SAME_CONTEXT 丟擲 NETWORK_FAILURE 丟擲 USER_INPUT 丟擲 PENDING_REQUEST 丟擲 CLIENT_UNSUPPORTED_OPERATION 返回 Promise 此 promise 將在遊戲切換到使用者選擇的環境時 被解析。否則此 promise 將被拒絕 （例如使用者退出對話方塊）。
createAsync( ) 嘗試在指定玩家和當前玩家之間建立環境或 切換環境。如果列出的玩家不是當前玩家的關聯玩家， 或玩家未提供進入新環境的許可權， 則返回的 promise 將被拒絕。 當遊戲切換到新環境時， promise 將被解析。 引數 playerID字串 玩家的編號 示例 console.log(FBInstant.context.getID());// 1122334455FBInstant.context .createAsync('12345678') .then(function() { console.log(FBInstant.context.getID()); // 5544332211 }); 丟擲 INVALID_PARAM 丟擲 SAME_CONTEXT 丟擲 NETWORK_FAILURE 丟擲 USER_INPUT 丟擲 PENDING_REQUEST 丟擲 CLIENT_UNSUPPORTED_OPERATION 返回 Promise 此 promise 將在遊戲切換到新環境時被解析， 在切換失敗時被拒絕。
getPlayersAsync( ) 獲取 #contextplayer 物件的陣列， 其中包含與當前環境相關的活躍玩家 （在過去 90 天內玩過遊戲的使用者）的資訊。這可能包含當前 玩家。 注意：只有當 FBInstant.startGameAsync() 被解析時，此 promise 才會解析。 示例 var contextPlayers = FBInstant.context.getPlayersAsync() .then(function(players) { console.log(players.map(function(player) { return { id: player.getID(), name: player.getName(), } })); });// [{id: '123456789', name: 'Luke'}, {id: '987654321', name: 'Leia'}] 丟擲 NETWORK_FAILURE 丟擲 CLIENT_UNSUPPORTED_OPERATION 丟擲 INVALID_OPERATION 返回 Promise<陣列>
getLocale( ) 當前的語言設定。根據這一結果確定當前的遊戲應本地化 為哪種語言。在 FBInstant.startGameAsync() 被解析之前，對應的值將不準確。 示例 // This function should be called after FBInstant.startGameAsync()// resolves.var locale = FBInstant.getLocale(); // 'en_US' 返回字串？ 當前的語言設定。
getPlatform( ) 當前執行遊戲的平臺。對應的值將始終為 null， 直至 FBInstant.initializeAsync() 被解析。 示例 // This function should be called after FBInstant.initializeAsync()// resolves.var platform = FBInstant.getPlatform(); // 'IOS' 返回平臺？
getSDKVersion( ) 表示此 SDK 版本的字串。 示例 // This function should be called after FBInstant.initializeAsync()// resolves.var sdkVersion = FBInstant.getSDKVersion(); // '2.0' 返回字串 SDK 版本。
initializeAsync( ) 初始化 SDK 庫。應在呼叫其他任何 SDK 函式 之前呼叫此函式。 示例 FBInstant.initializeAsync().then(function() { // Many properties will be null until the initialization completes. // This is a good place to fetch them: var locale = FBInstant.getLocale(); // 'en_US' var platform = FBInstant.getPlatform(); // 'IOS' var sdkVersion = FBInstant.getSDKVersion(); // '3.0' var playerID = FBInstant.player.getID();}); 丟擲 INVALID_OPERATION 返回 Promise 此 promise 將在 SDK 可以使用時被解析。
setLoadingProgress( ) 報告遊戲的初始載入進度。 引數 percentage數字 介於 0 和 100 之間的數字。 示例 FBInstant.setLoadingProgress(50); // Assets are 50% loaded 返回 void
getSupportedAPIs( ) 提供客戶端支援的 API 函式的列表。 示例 // This function should be called after FBInstant.initializeAsync()// resolves.FBInstant.getSupportedAPIs();// ['getLocale', 'initializeAsync', 'player.getID', 'context.getType', ...] 返回陣列<字串> 客戶端顯式支援的 API 函式 列表。
getEntryPointData( ) 返回與啟動遊戲的入口點相關的任何資料 物件。 物件內容由開發者定義，可通過不同平臺 的入口點觸發。對於較舊版本的移動客戶端， 以及沒有與特定入口點相關的資料時， 此函式會返回 null。 僅當 FBInstant.startGameAsync() 被解析後 才應呼叫此函式。 示例 // This function should be called after FBInstant.initializeAsync()// resolves.const entryPointData = FBInstant.getEntryPointData(); 返回物件？ 與當前入口點相關的資料。
getEntryPointAsync( ) 返回啟動遊戲的入口點 示例 // This function should be called after FBInstant.initializeAsync()// resolves.FBInstant.getEntryPointAsync().then(entrypoint => console.log(entrypoint));// 'admin_message' 返回字串 使用者啟動遊戲時所在的入口點的 名稱
setSessionData( ) 為當前環境設定與單個遊戲會話相關的 資料。 當遊戲需要更新當前的會話資料時， 應呼叫此函式。此會話資料可用於填充各種負載， 如玩遊戲 webhook。 引數 sessionData物件 一個隨機資料物件，轉變為字串後，必須小於 或等於 1000 個字元。 示例 FBInstant.setSessionData({coinsEarned: 10, eventsSeen: ['start', ...]}); 返回 void
startGameAsync( ) 表示遊戲已完成初始載入， 並準備就緒可以開始遊戲。當返回的 promise 被解析時， 環境資訊即為最新。 示例 FBInstant.startGameAsync().then(function() { myGame.start();}); 丟擲 INVALID_PARAM 丟擲 CLIENT_UNSUPPORTED_OPERATION 返回 Promise 此 promise 將在遊戲應該啟動時被解析。
shareAsync( ) 此函式會呼叫一個對話方塊，讓使用者以下列方式分享指定的內容：在 Messenger 中傳送訊息，或在使用者時間線上釋出帖子。可以在分享中新增資料塊， 通過此次分享啟動的每個遊戲會話 都可以通過 FBInstant.getEntryPointData() 訪問此資料塊。轉變為字串時， 此資料必須小於或等於 1000 個字元。使用者 可以選擇取消分享操作和關閉對話方塊， 但無論使用者實際是否分享了內容， 返回的 promise 都將在對話方塊關閉時解析。 引數 payloadSharePayload，指定要分享的內容。詳情 請參閱示例。 示例 FBInstant.shareAsync({ intent: 'REQUEST', image: base64Picture, text: 'X is asking for your help!', data: { myReplayData: '...' },}).then(function() { // continue with the game.}); 丟擲 INVALID_PARAM 丟擲 NETWORK_FAILURE 丟擲 PENDING_REQUEST 丟擲 CLIENT_UNSUPPORTED_OPERATION 丟擲 INVALID_OPERATION 返回 Promise 此 promise 將在分享完成或取消時 被解析。
updateAsync( ) 向 Facebook 通知遊戲內發生的更新。這會 暫時將控制權移交給 Facebook，且 Facebook 將確定要 根據更新內容採取什麼操作。返回的 promise 將在 Facebook 把 控制權返還給遊戲時解析/拒絕。 引數 payloadCustomUpdatePayload 描述更新的負載。 示例 // 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: 'Join The Fight', image: base64Picture, text: { default: 'X just invaded Y's village!', localizations: { ar_AR: 'X \u0641\u0642\u0637 \u063A\u0632\u062A ' + '\u0642\u0631\u064A\u0629 Y!', en_US: 'X just invaded Y's village!', es_LA: '\u00A1X acaba de invadir el pueblo de Y!', } } template: 'VILLAGE_INVASION', data: { myReplayData: '...' }, strategy: 'IMMEDIATE', notification: 'NO_PUSH',}).then(function() { // closes the game after the update is posted. FBInstant.quit();}); 丟擲 INVALID_PARAM 丟擲 PENDING_REQUEST 返回 Promise 此 promise 將在 Facebook 把控制權交還給遊戲時 被解析。
quit( ) 退出遊戲。 示例 FBInstant.quit(); 返回 void
logEvent( ) 通過 Facebook 分析記錄應用事件。請參閱 https://developers.facebook.com/docs/javascript/reference/v2.8#app_events 詳細瞭解 Fcaebook 分析。 引數 eventName字串 事件名稱。必須為 2 到 40 個字元， 且只能包含“”、“-”、“ ”和字母數字字元。 valueToSum數字 可選的數值，Facebook 分析利用此引數來 計算總和。 parameters物件 可選的物件，最多可包含 25 個要與事件一同記錄的鍵值對。鍵必須為 2 到 40 個字元， 且只能包含“”、“-”、“ ”和 字母數字字元。值的長度必須小於 100 個字元。 示例 var logged = FBInstant.logEvent( 'my_custom_event', 42, {custom_property: 'custom_value'},); 返回 APIError？ 如果事件記錄錯誤，將返回錯誤； 否則返回 null。
onPause( ) 設定發生暫停事件時將觸發的回撥。 引數 func函式 發生暫停事件時將呼叫的函式。 返回 void
getInterstitialAdAsync( ) 嘗試建立插屏廣告的例項。此例項可在之後 預載和顯示。 引數 placementID字串 在 Audience Network 設定中設定的 版位編號。 示例 FBInstant.getInterstitialAdAsync( 'my_placement_id',).then(function(interstitial) { interstitial.getPlacementID(); // 'my_placement_id'}); 丟擲 ADS_TOO_MANY_INSTANCES 丟擲 CLIENT_UNSUPPORTED_OPERATION 返回 Promise 此 promise 將在獲得 #adinstance 時被解析；在獲得 #apierror 時被拒絕 （如果未能建立）。
getRewardedVideoAsync( ) 嘗試建立獎勵式視訊廣告的例項。此例項可在之後 預載和顯示。 引數 placementID字串 在 Audience Network 設定中設定的 版位編號。 示例 FBInstant.getRewardedVideoAsync( 'my_placement_id',).then(function(rewardedVideo) { rewardedVideo.getPlacementID(); // 'my_placement_id'}); 丟擲 ADS_TOO_MANY_INSTANCES 丟擲 CLIENT_UNSUPPORTED_OPERATION 返回 Promise 此 promise 將在獲得 #adinstance 時被解析；在獲得 #apierror 時被拒絕 （如果未能建立）。
LocalizationsDict 代表特定字串的語言設定與翻譯之間的對映。 每個屬性均為可選且包含五個字元的 Facebook 語言程式碼，格式為 xx_XX。 請參閱https://www.facebook.com/translations/FacebookLocales.xml， 獲取受支援的語言程式碼的完整列表。 型別：物件
APIError 小遊戲 SDK 返回的 API 錯誤
code 相關的錯誤程式碼 型別：ErrorCodeType
message 描述錯誤的訊息 型別：字串
SignedPlayerInfo 代表玩家資訊，幷包含簽名， 簽名用於驗證對應資訊確實來源於 Facebook。
getPlayerID( ) 獲取玩家的編號。 返回字串 玩家的編號
getSignature( ) 用於驗證此物件確實來源於 Facebook 的簽名。此字串 使用 base64url 編碼， 並根據 OAuth 2.0 協議使用 HMAC 版本的應用金鑰簽名。 您可以通過以下 4 步進行驗證： 將簽名分為兩個部分，以“.”字元隔開。 通過 base64url 編碼對第一部分（編碼後的簽名）進行解碼。 通過 base64url 編碼對第二部分（響應負載）進行解碼， 第二部分應該是代表 JSON 物件（包含下列欄位）的字串： ** algorithm — 始終等於 HMAC-SHA256。 ** issued_at — 發出此響應的 unix 時間戳。 ** player_id — 玩家的唯一標識。 ** request_payload — 您在呼叫 FBInstant.player.getSignedPlayerInfoAsync 時 指定的 requestPayload 字串。 請採用 HMAC SHA-256 和您的應用金鑰雜湊處理 整個響應負載字串，並確定它等同於經編碼的簽名。 還建議您驗證響應負載中 的 issued_at 時間戳，確保請求是最近發出的。 應僅在您的伺服器中進行簽名驗證。不要在客戶端進行簽名驗證， 因為客戶端可能會洩漏您的應用金鑰。 示例 Eii6e636mz5J47sfqAYEK40jYAwoFqi3x5bxHkPG4Q4.eyJhbGdvcml0aG0iOiJITUFDLVNIQTI1NiIsImlzc3VlZF9hdCI6MTUwMDM5ODY3NSwicGxheWVyX2lkIjoiMTI0OTUyNTMwMTc1MjIwMSIsInJlcXVlc3RfcGF5bG9hZCI6Im15X2ZpcnN0X3JlcXVlc3QifQ 返回字串 簽名字串。
ConnectedPlayer 代表與當前玩家關聯的玩家的資訊。
getID( ) 獲取關聯玩家的編號。 返回字串 關聯玩家的編號
getName( ) 獲取玩家的全名。 返回字串？ 即玩家的全名
getPhoto( ) 獲取玩家公開頭像的網址。 返回字串？ 玩家公開頭像的網址
ContextPlayer 代表與當前玩家在相同環境中玩遊戲 的玩家的資訊。
getID( ) 獲取相同環境玩家的編號。 返回字串 相同環境玩家的編號
getName( ) 獲取經本地化顯示的玩家姓名。 返回字串？ 經本地化顯示的玩家姓名。
getPhoto( ) 獲取玩家公開頭像的網址。 返回字串？ 玩家公開頭像的網址
AdInstance 代表廣告例項。
getPlacementID( ) 返回此廣告例項的 Audience Network 版位編號。
loadAsync( ) 預載入廣告。返回的 promise 將在預載入完成時被解析， 在預載入失敗時被拒絕。 示例 FBInstant.getInterstitialAdAsync( 'my_placement_id',).then(function(interstitial) { return interstitial.loadAsync();}).then(function() { // Ad loaded}); 丟擲 ADS_FREQUENT_LOAD 丟擲 ADS_NO_FILL 丟擲 INVALID_PARAM 丟擲 NETWORK_FAILURE 返回 Promise
showAsync( ) 代表廣告。返回的 promise 將在使用者 觀看完廣告時被解析，在廣告展示失敗或 使用者在廣告展示期間關閉廣告時被拒絕。 示例 var ad = null;FBInstant.getRewardedVideoAsync( 'my_placement_id',).then(function(rewardedVideo) { ad = rewardedVideo; return ad.loadAsync();}).then(function() { // Ad loaded return ad.showAsync();}).then(function() { // Ad watched}); 丟擲 ADS_NOT_LOADED 丟擲 INVALID_PARAM 丟擲 NETWORK_FAILURE 返回 Promise
ContextFilter 適用於環境選擇操作的篩選條件。 “NEW_CONTEXT_ONLY”— 僅顯示之前玩遊戲未使用過的環境。 “INCLUDE_EXISTING_CHALLENGES”— 包括“當前挑戰”部分， 顯示玩家積極在其中玩遊戲的環境。 “NEW_PLAYERS_ONLY”— 在包含個人資訊的部分， 篩選出之前未玩過遊戲的使用者， 型別：("NEW_CONTEXT_ONLY" | "INCLUDE_EXISTING_CHALLENGES" | "NEW_PLAYERS_ONLY")
平臺 代表使用者當前在哪個平臺玩遊戲。 型別：("IOS" | "ANDROID" | "WEB" | "MOBILE_WEB")
ContextSizeResponse 如果當前環境的規模介於物件中 指定的 minSize 和 maxSize 值之間， answer 欄位為 true，否則為 false。 型別：{answer: boolean, minSize: number?, maxSize: number?}
SharePayload 代表使用者分享的內容。 型別：物件 屬性 intent("INVITE" | "REQUEST" | "CHALLENGE" | "SHARE") 表示分享的意圖。 image字串 要分享的 base64 編碼圖片。 text字串 要分享的文字訊息。 data物件？ 要附加到分享中的資料塊。通過分享 開始的所有遊戲會話都可以通過 FBInstant.getEntryPointData() 訪問此資料塊。
錯誤程式碼 小遊戲 API 可能會返回的錯誤程式碼 屬性 ADS_FREQUENT_LOAD字串 廣告載入太頻繁。 ADS_NO_FILL字串 我們無法向當前的使用者投放 廣告。如果使用者在裝置中退訂基於興趣的廣告 ，或我們沒有廣告可展示給該使用者，就會出現這種情況 ADS_NOT_LOADED字串 嘗試顯示此前未成功 載入的廣告。 ADS_TOO_MANY_INSTANCES字串 同時展示的廣告例項 太多。建議您先載入和展示現有廣告例項，再新建廣告。 ANALYTICS_POST_EXCEPTION字串 分析 API 在嘗試釋出事件 時遇到問題。 CLIENT_REQUIRES_UPDATE字串 [已停用] — 客戶端要求獲得 更新，以便訪問返回此結果的功能。如果在網頁端 返回這一結果，則意味著該網頁客戶端還不支援 此功能。v5.0 及更高版本已停用這一程式碼，以便支援 CLIENT_UNSUPPORTED_OPERATION CLIENT_UNSUPPORTED_OPERATION字串 客戶端不支援 當前操作。這可能是因為客戶端版本或平臺不提供 相關支援，或不允許對遊戲或玩家執行此 操作。 INVALID_OPERATION字串 所請求的操作無效， 或表示當前的遊戲狀態。這包括違反限制 （如超出儲存上限）或不適用於特定狀態 （如在獨立的環境中針對特定環境發出請求） 的情況。 INVALID_PARAM字串 傳遞給 API 的引數 無效。可表示錯誤型別、引數的無效數字，或 語義問題（例如，將不可序列化的物件傳遞到 序列化函式）。 NETWORK_FAILURE字串 客戶端處理網路請求時 出現問題。這可能是由暫時性問題導致的， 如玩家的網路連線中斷。 PENDING_REQUEST字串 表示因存在與此請求衝突的 一項請求而被拒絕。例如，當某個依賴於 Facebook 使用者介面的請求處於待處理狀態時， 我們就會拒絕顯示 Facebook 使用者介面的其他任何呼叫。 SAME_CONTEXT字串 遊戲嘗試切換到 當前環境。 UNKNOWN字串 發生了未知或未指定的問題。這是 客戶端未指定程式碼時返回的預設錯誤程式碼。 USER_INPUT字串 使用者的選擇導致 被拒絕。例如，如果遊戲呼叫環境切換對話方塊， 而玩家關閉此對話方塊， 則 promise 拒絕中就會包含此錯誤程式碼。 示例 FBInstant.startGameAsync().catch(function(e) { console.log(e);});// {code: 'CLIENT_UNSUPPORTED_OPERATION', message: '...'}
ErrorCodeType 小遊戲錯誤程式碼，#errorcode 中的一種 型別：字串
CustomUpdatePayload 代表 FBInstant.updateAsync 的自定義更新。 型別：物件 屬性 action字串 對於自定義更新，此屬性應為“CUSTOM”。 template字串 此自定義更新所使用模板的編號。 模板應在 fbapp-config.json 中預定義。請參閱 [捆綁包配置文件]https://developers.facebook.com/docs/games/instant-games/bundle-config，獲取有關 fbapp-config.json 的文件。 cta（字串？| LocalizableContent？） 可選的行動號召按鈕 文字。預設情況下，我們會使用經本地化的“Play”作為按鈕文字。 若要提供自定義行動號召的本地化版本， 應傳遞一個包含預設行動號召的物件作為“default”值，以及將語言鍵對映到翻譯的 另一個物件作為“localizations”值。 image字串 base64 編碼圖片的資料網址。 text（字串 | LocalizableContent） 一條文字訊息， 或者是一個包含預設文字作為“default”值的物件 以及另一個將語言鍵對映到翻譯內容作為“localizations”值的物件。 data物件？ 要附加到更新中的資料塊。通過更新 開始的所有遊戲會話都可以通過 FBInstant.getEntryPointData() 訪問此資料塊。轉變為字串時， 此資料塊必須小於或等於 1000 個字元。 strategy字串？ 指定更新的釋出 方式。可以是下列方式之一： “IMMEDIATE”— 更新應立即釋出。 “LAST”— 更新應在遊戲會話結束時釋出。使用 “LAST”策略傳送的是最近傳送的更新。 “IMMEDIATE_CLEAR”— 更新將立即釋出，並清除其他任何待處理的 更新（如通過“LAST”策略釋出的更新）。 如果未指定策略，我們將預設為“IMMEDIATE”。 notification字串？ 指定自定義更新的 通知設定。可以是“NO_PUSH”或“PUSH”，預設為“NO_PUSH”。 僅將推送通知用於 對接收人來說非常顯著且可立即操作的更新。另請注意，並不一定 會傳送推送通知，具體取決於使用者設定和平臺政策。
LocalizableContent 代表一個字串，其中包含最終使用的本地化內容和預設值。 型別：物件 屬性 default字串 要使用的字串的預設值 （檢視者的語言設定不是 localizations 物件中的鍵時）。 localizationsLocalizationsDict 指定每種語言設定中用於觀看者 的字串。 請參閱 https://www.facebook.com/translations/FacebookLocales.xml， 獲取受支援的完整語言列表。
為方便大家群策群力，我們建立了一個 Facebook Instant Game 交流群：814298516 。 歡迎同學們加入交流開發和運營經驗。
