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 < > 以物件解析的 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(),

}

}));

});// [{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

返回？

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 天內玩過遊戲的使用者）的資訊。這可能包含當前玩家。

注意：只有當 FBInstant.startGameAsync() 被解析時，此 promise 才會解析。

示例

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 < 陣列 < >>

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 都將在對話方塊關閉時解析。

引數

·

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 CustomUpdatePayload 描述更新的負載。

·

示例

// 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

·

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

返回？如果事件記錄錯誤，將返回錯誤；否則返回 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 將在獲得時被解析；在獲得時被拒絕（如果未能建立）。

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

LocalizationsDict

代表特定字串的語言設定與翻譯之間的對映。每個屬性均為可選且包含五個字元的 Facebook 語言程式碼，格式為 xx_XX。請參閱，獲取受支援的語言程式碼的完整列表。

型別：物件

APIError

小遊戲 SDK 返回的 API 錯誤

code

相關的錯誤程式碼

型別：

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

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

型別：字串

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”。僅將推送通知用於對接收人來說非常顯著且可立即操作的更新。另請注意，並不一定會傳送推送通知，具體取決於使用者設定和平臺政策。

·

LocalizableContent

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

型別：物件

屬性

·

default 字串要使用的字串的預設值（檢視者的語言設定不是 localizations 物件中的鍵時）。

·

localizations 指定每種語言設定中用於觀看者的字串。請參閱，獲取受支援的完整語言列表。

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

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