Facebook 遊戲開發更新文件

API 參考文件 v6.0

更新日誌

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

2. [公測版] 遊戲內切換 我們還針對遊戲內交叉推廣引入了一個新 API。它目前處於封測階段，如果您有興趣在自己的遊戲中幫忙測試遊戲內切換 API 的整合效果，請聯絡您的合作伙伴經理！

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 < > 以物件解析的 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 物件的陣列，這些物件包含與當前玩家關聯的玩家的資訊。

示例

var connectedPlayers = FBInstant.player.getConnectedPlayersAsync()

.then(function(players) {

console.log(players.map(function(player) {

return {

id: player.getID(),

}

}));

});// [{id: '123456789', name: 'Paul Atreides'}, {id: '987654321', name: 'Duncan Idaho'}]

·

丟擲 NETWORK_FAILURE

·

丟擲 CLIENT_UNSUPPORTED_OPERATION

·

返回 Promise < 陣列 < >> 此 promise 將在獲得關聯玩家物件列表時被解析。注意：只有當 FBInstant.startGameAsync() 被解析時，此 promise 才會解析。

context

包含與當前遊戲環境相關的功能和屬性。

getID( )

當前遊戲環境的唯一標識。這表示玩遊戲的特定環境（例如：特定的 Messenger 對話或 Facebook 帖子）。如果使用者在獨立環境中玩遊戲，則此標識將為 null。僅當 FBInstant.startGameAsync 被解析後才應呼叫此函式。

示例

// This function should be called after FBInstant.startGameAsync()// resolves.var contextID = FBInstant.context.getID();

返回字串？當前遊戲環境的唯一標識。

getType( )

當前遊戲環境的型別。 POST — 一個 Facebook 帖子。 THREAD — 一個 Messenger 對話。 GROUP — 一個 Facebook 小組。 SOLO — 預設環境，玩家是唯一的參與者。

僅當 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

返回？

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( )

獲取物件的陣列，其中包含與當前環境相關的活躍玩家（在過去 90 天內玩過遊戲的使用者）的資訊。這可能包含當前玩家。

示例

var contextPlayers = FBInstant.context.getPlayersAsync()

.then(function(players) {

console.log(players.map(function(player) {

return {

id: player.getID(),

}

}));

});// [{id: '123456789', name: 'Luke'}, {id: '987654321', name: 'Leia'}]

·

丟擲 NETWORK_FAILURE

·

丟擲 CLIENT_UNSUPPORTED_OPERATION

·

丟擲 INVALID_OPERATION

·

返回 Promise < 陣列 < >>

支付

[封閉公測] 包含與遊戲商品的支付和購買相關的函式和屬性。

getCatalogAsync( )

獲取遊戲的商品目錄。

示例

FBInstant.payments.getCatalogAsync().then(function (catalog) {

console.log(catalog); // [{productID: '12345', ...}, ...]});

·

丟擲 CLIENT_UNSUPPORTED_OPERATION

·

丟擲 PAYMENTS_NOT_INITIALIZED

·

丟擲 NETWORK_FAILURE

·

返回 Promise < 陣列 < >> 登記到遊戲的一組商品。

purchaseAsync( )

開始特定商品的購買流程。

引數

·

purchaseConfig 該項購買的配置詳情。

·

示例

FBInstant.payments.purchaseAsync({

productID: '12345',

developerPayload: 'foobar',}).then(function (purchase) {

console.log(purchase);

// {productID: '12345', purchaseToken: '54321', developerPayload: 'foobar', ...}});

·

丟擲 CLIENT_UNSUPPORTED_OPERATION

·

丟擲 PAYMENTS_NOT_INITIALIZED

·

丟擲 INVALID_PARAM

·

丟擲 NETWORK_FAILURE

·

返回 Promise < > 此 promise 將在玩家成功購買商品時被解析，否則會被拒絕。

getPurchasesAsync( )

獲取玩家未消費的所有購買商品。最佳做法是，遊戲在客戶端表明已準備好執行支付相關操作時，立即獲取當前玩家的購買商品。遊戲隨後可處理和消費正在等待被消費的任何購買商品。

示例

FBInstant.payments.getPurchasesAsync().then(function (purchases) {

console.log(purchase);

// [{productID: '12345', ...}, ...]});

·

丟擲 CLIENT_UNSUPPORTED_OPERATION

·

丟擲 PAYMENTS_NOT_INITIALIZED

·

丟擲 NETWORK_FAILURE

·

返回 Promise < 陣列 < >> 玩家為遊戲購買的一組商品。

consumePurchaseAsync( )

消費當前玩家擁有的特定購買商品。在為玩家配置商品效果之前，遊戲應先請求消費已購買的商品。購買的商品成功消費後，遊戲應立即向玩家呈現購買商品的效果。

引數

·

purchaseToken 字串應消費的購買商品的購買口令。

·

示例

FBInstant.payments.consumePurchaseAsync('54321').then(function () {

// Purchase successfully consumed!

// Game should now provision the product to the player});

·

丟擲 CLIENT_UNSUPPORTED_OPERATION

·

丟擲 PAYMENTS_NOT_INITIALIZED

·

丟擲 INVALID_PARAM

·

丟擲 NETWORK_FAILURE

·

返回 Promise 此 promise 在成功消費已購買的商品時被解析。

onReady( )

設定一個回撥，在支付操作可進行時觸發。

引數

·

callback 函式當支付可進行時執行的回撥函式。

·

示例

FBInstant.payments.onReady(function () {

console.log('Payments Ready!')});

返回 void

getLocale( )

當前的語言設定。根據這一結果確定當前的遊戲應本地化為哪種語言。在 FBInstant.startGameAsync() 被解析之前，對應的值將不準確。

示例

// This function should be called after FBInstant.startGameAsync()// resolves.var locale = FBInstant.getLocale(); // 'en_US'

返回字串？當前的語言設定。

getPlatform( )

為當前環境設定與單個遊戲會話相關的資料。

當遊戲需要更新當前的會話資料時，應呼叫此函式。此會話資料可用於填充各種負載，如玩遊戲 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 都將在對話方塊關閉時解析。

引數

·

payload ，指定要分享的內容。詳情請參閱示例。

·

示例

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 把控制權返還給遊戲時解析/拒絕。

引數

·

payload UpdatePayload 描述更新的負載。

·

示例

// 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!',

}

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

strategy: 'IMMEDIATE',

notification: 'NO_PUSH',}).then(function() {

// closes the game after the update is posted.

FBInstant.quit();});

·

丟擲 INVALID_PARAM

·

丟擲 PENDING_REQUEST

·

丟擲 INVALID_OPERATION

·

返回 Promise 此 promise 將在 Facebook 把控制權交還給遊戲時被解析。

switchGameAsync( )

請求客戶端切換到另一個小遊戲。切換失敗時， API 將拒絕，否則客戶端將載入新遊戲。

引數

·

appID 字串要切換到的小遊戲相應的應用編號。應用必須為小遊戲，且必須和當前遊戲屬於同一商家所有。要將不同遊戲關聯到相同商家，您可使用商務管理平臺： https://developers.facebook.com/docs/apps/business-manager#update-business 。

·

data 字串？可選的資料負載。這將設為要切換到的遊戲的入口點資料。轉變為字串時，必須小於或等於 1000 個字元。

·

示例

FBInstant.switchGameAsync('12345678').catch(function (e) {

// Handle game change failure});

·

丟擲 USER_INPUT

·

丟擲 INVALID_PARAM

·

丟擲 PENDING_REQUEST

·

丟擲 CLIENT_REQUIRES_UPDATE

·

返回 Promise

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

返回？如果事件記錄錯誤，將返回錯誤；否則返回 null。

onPause( )

設定發生暫停事件時將觸發的回撥。

引數

·

func 函式發生暫停事件時將呼叫的函式。

·

示例

FBInstant.onPause(function() {

console.log('Pause event was triggered!');})

返回 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 將在獲得時被解析；在獲得時被拒絕（如果未能建立）。

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 將在獲得時被解析；在獲得時被拒絕（如果未能建立）。

matchPlayerAsync( )

[封閉公測] 嘗試將當前玩家與等待他人加入遊戲的其他玩家進行匹配。如果匹配成功，將為匹配的玩家建立一個新的 Messenger 群聊，且玩家的遊戲環境將切換到該群聊。

引數

·

matchTag 字串？玩家的可選額外資訊，可用於將玩家加到具有相似玩家的群聊中。具有完全相同標籤的玩家才會加入同一群聊。標籤只能包含字母、數字和下劃線，且長度不能超過 100 個字元。

·

switchContextWhenMatched boolean 可選的額外引數，指定當找到匹配時，是否將玩家立即切換到新環境。預設設定為 false，亦即玩家在匹配成功後，需要明確點選玩遊戲按鈕才會切換到新環境。

·

示例

FBInstant

.matchPlayerAsync('level1')

.then(function() {

console.log(FBInstant.context.getID());

// 12345

});

FBInstant

.matchPlayerAsync()

.then(function() {

console.log(FBInstant.context.getID());

// 3456

});

FBInstant

.matchPlayerAsync(null, true)

.then(function() {

console.log(FBInstant.context.getID());

// 3456

});

·

丟擲 INVALID_PARAM

·

丟擲 NETWORK_FAILURE

·

丟擲 USER_INPUT

·

丟擲 PENDING_REQUEST

·

丟擲 CLIENT_UNSUPPORTED_OPERATION

·

丟擲 INVALID_OPERATION

·

返回 Promise 當玩家已加入群聊並切換到群聊環境時，此 promise 被解析。

checkCanPlayerMatchAsync( )

[封閉公測] 檢查當前玩家是否符合 matchPlayerAsync API 的條件。

示例

FBInstant

.checkCanPlayerMatchAsync()

.then(canMatch => {

if (canMatch) {

FBInstant.matchPlayerAsync('level1');

}

});

·

丟擲 NETWORK_FAILURE

·

丟擲 CLIENT_UNSUPPORTED_OPERATION

·

返回 Promise < boolean > 當玩家符合與其他玩家匹配的條件時，此 promise 被解析為 true，否則解析為 false。

getLeaderboardAsync( )

獲取這款小遊戲中的特有排行榜。

引數

·

name 字串排行榜的名稱。小遊戲的每個排行榜必須具有唯一的名稱。

·

示例

FBInstant.getLeaderboardAsync('my_awesome_leaderboard')

.then(leaderboard => {

console.log(leaderboard.getName()); // 'my_awesome_leaderboard'

});

·

丟擲 LEADERBOARD_NOT_FOUND

·

丟擲 NETWORK_FAILURE

·

丟擲 CLIENT_UNSUPPORTED_OPERATION

·

丟擲 INVALID_OPERATION

·

丟擲 INVALID_PARAM

·

返回 Promise < > 此 promise 在獲得匹配的排行榜時被解析，在未找到匹配時被拒絕。

LocalizationsDict

代表特定字串的語言設定與翻譯之間的對映。每個屬性均為可選且包含五個字元的 Facebook 語言程式碼，格式為 xx_XX。請參閱 https://origincache.facebook.com/developers/resources/?id=FacebookLocales.xml ，獲取受支援的語言程式碼的完整列表。

型別：物件

APIError

小遊戲 SDK 返回的 API 錯誤

code

相關的錯誤程式碼

型別：

message

描述錯誤的訊息

型別：字串

ConnectedPlayer

代表與當前玩家關聯的玩家的資訊。

getID( )

獲取關聯玩家的編號。

返回字串關聯玩家的編號

getName( )

獲取玩家的全名。

返回字串？即玩家的全名

getPhoto( )

獲取玩家公開頭像的網址。

返回字串？玩家公開頭像的網址

SignedPlayerInfo

代表玩家資訊，幷包含簽名，簽名用於驗證對應資訊確實來源於 Facebook。

getPlayerID( )

獲取玩家的編號。

示例

FBInstant.player.getSignedPlayerInfoAsync()

.then(function (result) {

result.getPlayerID(); // same value as FBInstant.player.getID()

});

返回字串玩家的編號

getSignature( )

用於驗證此物件確實來源於 Facebook 的簽名。此字串使用 base64url 編碼，並根據 OAuth 2.0 協議使用 HMAC 版本的應用金鑰簽名。

您可以透過以下步驟進行驗證：

1. 將簽名分為兩個部分，以 “.”字元隔開。

2.

對第一部分（編碼簽名）執行以下替換操作：

3.

o

將短橫線 ('-') 替換為加號 ('+')

o

將下劃線 ('_') 替換為正斜槓 ('/')

o

4.

使用 base64url 編碼對產生的字串解碼。

5.

6.

透過 base64url 編碼對第二部分（響應負載）進行解碼，第二部分應該是代表 JSON 物件（包含下列欄位）的字串：

7.

o

algorithm — 始終等於 HMAC-SHA256

o

issued_at — 發出此響應的 unix 時間戳。

o

player_id — 玩家的唯一標識。

o

request_payload — 呼叫 FBInstant.player.getSignedPlayerInfoAsync 時指定的 requestPayload 字串。

o

8.

請採用 HMAC SHA-256 和您的應用金鑰雜湊處理整個響應負載字串，並確定它等同於經編碼的簽名。

9.

10. 還建議您驗證響應負載中的 issued_at 時間戳，確保請求是最近發出的。

應僅在您的伺服器中進行簽名驗證。 不要在客戶端進行簽名驗證，因為客戶端可能會洩漏您的應用金鑰。

示例

//// In your game's client//FBInstant.player.getSignedPlayerInfoAsync('my_payload')

.then(function (result) {

MyServer.send(result.getSignature());

// Example result.getSignature()

// Eii6e636mz5J47sfqAYEK40jYAwoFqi3x5bxHkPG4Q4.eyJhbGdvcml0aG0iOiJITUFDLVNIQTI1NiIsImlzc3VlZF9hdCI6MTUwMDM5ODY3NSwicGxheWVyX2lkIjoiMTI0OTUyNTMwMTc1MjIwMSIsInJlcXVlc3RfcGF5bG9hZCI6Im15X2ZpcnN0X3JlcXVlc3QifQ

});

//// In your server (node.js example)//const CryptoJS = require('crypto-js');var firstpart = signedRequest.split('.')[0];

firstpart = firstpart.replace(/-/g, '+').replace(/_/g, '/');const signature = CryptoJS.enc.Base64.parse(firstpart).toString();const dataHash = CryptoJS.HmacSHA256(signedRequest.split('.')[1], '<APP_SECRET>').toString();var isValid = signature === dataHash;

const json = crypto.enc.Base64.parse(signedRequest.split('.')[1]).toString(crypto.enc.Utf8);const encodedData = JSON.parse(json);

// Example encodedData:// {// algorithm: 'HMAC-SHA256',// issued_at: 1520009634,// player_id: '123456789',// request_payload: 'my_payload'// }

返回字串簽名字串。

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

·

獲取排行榜中玩家上榜分數的總數量。

示例

FBInstant.getLeaderboardAsync('my_leaderboard')

.then(function(leaderboard) {

return leaderboard.getEntryCountAsync();

})

.then(function(count) { console.log(count); }); // 24

·

丟擲 NETWORK_FAILURE

·

返回 Promise < 數字 > 玩家的唯一標識。

setScoreAsync( )

更新玩家的分數。如果玩家已有分數，只有新分數更好時，才會替換舊分數。注意：如果排行榜與特定環境關聯，遊戲必須處於該環境，才能為玩家設定分數。

引數

·

score 數字玩家的新分數。必須為 64 位整數。

·

extraData 字串 ？ = ion。 與儲存的分數關聯的後設資料。大小必須小於 2KB。

·

示例

FBInstant.getLeaderboardAsync('my_leaderboard')

.then(function(leaderboard) {

return leaderboard.setScoreAsync(42, '{race: "elf", level: 3}');

})

.then(function(entry) {

console.log(entry.getScore()); // 42

console.log(entry.getExtraData()); // '{race: "elf", level: 3}'

});

·

丟擲 LEADERBOARD_WRONG_CONTEXT

·

丟擲 NETWORK_FAILURE

·

丟擲 INVALID_PARAM

·

丟擲 INVALID_OPERATION

·

返回 Promise < > 解析為更新後玩家在排行榜的當前上榜分數。

getPlayerEntryAsync( )

檢索當前玩家的排行榜上榜分數，或在玩家尚無上榜分數時返回 null。

示例

FBInstant.getLeaderboardAsync('my_leaderboard')

.then(function(leaderboard) {

return leaderboard.getPlayerEntryAsync();

})

.then(function(entry) {

console.log(entry.getRank()); // 2

console.log(entry.getScore()); // 42

console.log(entry.getExtraData()); // '{race: "elf", level: 3}'

});

·

丟擲 NETWORK_FAILURE

·

丟擲 INVALID_OPERATION

·

返回 Promise < >？解析為玩家在排行榜的當前上榜分數。

getEntriesAsync( )

檢索一組排行榜上榜分數，按排行榜上的得分名次排序。

引數

·

count 數字嘗試從排行榜獲取的上榜分數總數量。如果未指定，預設為 10。每條查詢命令最多可獲取 100 個上榜分數。

·

offset 數字從排行榜頂部檢索上榜分數的偏移量。

·

示例

FBInstant.getLeaderboardAsync('my_leaderboard')

.then(function(leaderboard) {

return leaderboard.getEntriesAsync();

})

.then(function(entries) {

console.log(entries.length); // 10

console.log(entries[0].getRank()); // 1

console.log(entries[0].getScore()); // 42

console.log(entries[1].getRank()); // 2

console.log(entries[1].getScore()); // 40

});

FBInstant.getLeaderboardAsync('my_leaderboard')

.then(function(leaderboard) {

return leaderboard.getEntriesAsync(5, 3);

})

.then(function(entries) {

console.log(entries.length); // 5

console.log(entries[0].getRank()); // 4

console.log(entries[0].getScore()); // 34

console.log(entries[1].getRank()); // 5

console.log(entries[1].getScore()); // 31

});

·

丟擲 NETWORK_FAILURE

·

返回 Promise < 陣列 < >> 解析為與查詢條件相符的排行榜上榜分數。

商品

表示遊戲的商品資訊。

型別：物件

屬性

·

title 字串商品的標題

·

productID 字串商品在遊戲中的特定標識

·

description 字串？商品說明

·

imageURI 字串？商品相關圖片的連結

·

price 字串商品的價格

·

priceCurrencyCode 字串商品的貨幣程式碼

·

ContextFilter

適用於環境選擇操作的篩選條件。 “NEW_CONTEXT_ONLY”— 僅顯示之前玩遊戲未使用過的環境。 “INCLUDE_EXISTING_CHALLENGES”— 包括“當前挑戰”部分，顯示玩家積極在其中玩遊戲的環境。 “NEW_PLAYERS_ONLY”— 在包含個人資訊的部分，篩選出之前未玩過遊戲的使用者，

型別： ( "NEW_CONTEXT_ONLY" | "INCLUDE_EXISTING_CHALLENGES" | "NEW_PLAYERS_ONLY" )

購買

表示遊戲商品的單筆購買。

型別：物件

屬性

·

developerPayload 字串？開發者指定的字串，在商品購買期間提供

·

paymentID 字串購買交易的標識

·

productID 字串商品在遊戲中的特定標識

·

purchaseTime 字串購買發生時的 Unix 時間戳

·

purchaseToken 字串代表該筆購買的一個口令，可用來消費購買的商品

·

signedRequest 購買請求的伺服器簽名程式碼

·

平臺

代表使用者當前在哪個平臺玩遊戲。

型別： ( "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 的引數無效。可表示錯誤型別、引數的無效數字，或語義問題（例如，將不可序列化的物件傳遞到序列化函式）。

·

LEADERBOARD_NOT_FOUND 字串找不到所請求名稱的排行榜。這是因為排行榜尚不存在，或其名稱與遊戲中登記的任何排行榜配置都不匹配。

·

LEADERBOARD_WRONG_CONTEXT 字串嘗試寫入的排行榜關聯了不同於當前玩遊戲環境的其他環境。

·

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: '...'}

UpdateAction

表示要執行的更新操作型別。

屬性

·

CUSTOM 字串一項自定義更新，所有內容都由遊戲指定。

·

LEADERBOARD 字串與小遊戲排行榜相關的一項更新。

·

ErrorCodeType

小遊戲錯誤程式碼，中的一種

型別：字串

SignedPurchaseRequest

型別：字串

示例

Eii6e636mz5J47sfqAYEK40jYAwoFqi3x5bxHkPG4Q4.eyJhbGdvcml0aG0iOiJITUFDLVNIQTI1NiIsImlzc3VlZF9hdCI6MTUwMDM5ODY3NSwicGxheWVyX2lkIjoiMTI0OTUyNTMwMTc1MjIwMSIsInJlcXVlc3RfcGF5bG9hZCI6Im15X2ZpcnN0X3JlcXVlc3QifQ

PurchaseConfig

註冊到遊戲的商品的購買請求配置。

型別：物件

屬性

·

productID 字串要購買商品的標識

·

developerPayload 字串？由開發者指定的可選負載，包含在所返回購買的簽名請求中。

·

CustomUpdatePayload

代表 FBInstant.updateAsync 的自定義更新。

型別：物件

屬性

·

action 對於自定義更新，此屬性應為“CUSTOM”。

·

template 字串此自定義更新所使用模板的編號。模板應在 fbapp-config.json 中預定義。請參閱 [捆綁包配置文件] https://developers.facebook.com/docs/games/instant-games/bundle-config ，獲取有關 fbapp-config.json 的文件。

·

cta （字串 ？ | ？）可選的行動號召按鈕文字。預設情況下，我們會使用經本地化的“Play”作為按鈕文字。若要提供自定義行動號召的本地化版本，應傳遞一個包含預設行動號召的物件作為“default”值，以及將語言鍵對映到翻譯的另一個物件作為“localizations”值。

·

image 字串 base64 編碼圖片的資料網址。

·

text （字串 | ）一條文字訊息，或者是一個包含預設文字作為“default”值的物件以及另一個將語言鍵對映到翻譯內容作為“localizations”值的物件。

·

data 物件？要附加到更新中的資料塊。透過更新開始的所有遊戲會話都可以透過 FBInstant.getEntryPointData() 訪問此資料塊。轉變為字串時，此資料塊必須小於或等於 1000 個字元。

·

strategy 字串？指定更新的釋出方式。可以是下列方式之一： “IMMEDIATE”— 更新應立即釋出。 “LAST”— 更新應在遊戲會話結束時釋出。使用 “LAST”策略傳送的是最近傳送的更新。 “IMMEDIATE_CLEAR”— 更新將立即釋出，並清除其他任何待處理的更新（如透過“LAST”策略釋出的更新）。如果未指定策略，我們將預設為“IMMEDIATE”。

·

notification 字串？指定自定義更新的通知設定。可以是“NO_PUSH”或“PUSH”，預設為“NO_PUSH”。僅將推送通知用於對接收人來說非常顯著且可立即操作的更新。另請注意，並不一定會傳送推送通知，具體取決於使用者設定和平臺政策。

·

LeaderboardUpdatePayload

表示 FBInstant.updateAsync 的一項排行榜更新。

型別：物件

屬性

·

action 對於排行榜更新，此屬性應為 “LEADERBOARD”。文字。預設情況下，我們會使用經本地化的“Play Now”作為按鈕文字。

·

name 字串所更新排行榜的名稱。

·

text 字串？可選的文字訊息。如果未指定，將會提供一條經本地化的回退訊息。

·

LocalizableContent

代表一個字串，其中包含最終使用的本地化內容和預設值。

型別：物件

屬性

與上榜分數相關玩家的詳情。

getName( )

獲取經本地化顯示的玩家姓名。

示例

leaderboard.setScoreAsync(9001)

.then(function(entry) {

console.log(entry.getPlayer().getName()); // Sally

});

返回字串經本地化顯示的玩家姓名。

getPhoto( )

返回玩家公開頭像的網址。

示例

leaderboard.setScoreAsync(9001)

.then(function(entry) {

console.log(entry.getPlayer().getPhoto()); // <photo_url>

});

返回字串？玩家公開頭像的網址。

getID( )

獲取玩家在遊戲中的唯一標識。

示例

leaderboard.setScoreAsync(9001)

.then(function(entry) {

console.log(entry.getPlayer().getID()); // 12345678

});

返回字串？玩家在遊戲中的標識。

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

Facebook 小遊戲開發更新文件 API 參考文件 v6.0

Facebook 遊戲開發更新文件

API 參考文件 v6.0

更新日誌

FBInstant

player

getID( )

getSignedPlayerInfoAsync( )

getName( )

getPhoto( )

getDataAsync( )

setDataAsync( )

flushDataAsync( )

getStatsAsync( )

setStatsAsync( )

incrementStatsAsync( )

getConnectedPlayersAsync( )

context

getID( )

getType( )

isSizeBetween( )

switchAsync( )

chooseAsync( )

createAsync( )

getPlayersAsync( )

支付

getCatalogAsync( )

purchaseAsync( )

getPurchasesAsync( )

consumePurchaseAsync( )

onReady( )

getLocale( )

getPlatform( )

getSDKVersion( )

initializeAsync( )

setLoadingProgress( )

getSupportedAPIs( )

getEntryPointData( )

getEntryPointAsync( )

setSessionData( )

startGameAsync( )

shareAsync( )

updateAsync( )

switchGameAsync( )

quit( )

logEvent( )

onPause( )

getInterstitialAdAsync( )

getRewardedVideoAsync( )

matchPlayerAsync( )

checkCanPlayerMatchAsync( )

getLeaderboardAsync( )

LocalizationsDict

APIError

code

message

ConnectedPlayer

getID( )

getName( )

getPhoto( )

SignedPlayerInfo

getPlayerID( )

getSignature( )

ContextPlayer

getID( )

getName( )

getPhoto( )

AdInstance

getPlacementID( )

loadAsync( )

showAsync( )

排行榜

getName( )

getContextID( )

getEntryCountAsync( )

setScoreAsync( )

getPlayerEntryAsync( )

getEntriesAsync( )

商品

ContextFilter