YouTube 遊戲角落 SDK 參考資料

ytgame

YouTube Playables SDK 的頂層命名空間。

這是目前視窗中全域範圍的變數。請勿覆寫這個變數。
命名空間
ads
🧪 公開預先發布版 API：可能隨時變更，恕不另行通知。
engagement
與玩家參與度相關的函式和屬性。
game
與一般遊戲行為相關的函式和屬性。
health
與遊戲健康相關的函式和屬性。
system
與 YouTube 系統相關的函式和屬性。
列舉
SdkErrorType
YouTube Playables SDK 擲回的錯誤類型。
類別
SdkError
YouTube Playables SDK 擲回的錯誤物件。
變數
IN_PLAYABLES_ENV
遊戲是否在可播放環境中執行。
SDK_VERSION
YouTube Playables SDK 版本。
另請參閱

列舉

Const SdkErrorType

SdkErrorType
YouTube Playables SDK 擲回的錯誤類型。
列舉成員
API_UNAVAILABLE
API 暫時無法使用。

如果玩家處於關鍵流程中，請要求他們稍後再試。
INVALID_PARAMS
使用無效參數呼叫 API。
SIZE_LIMIT_EXCEEDED
呼叫 API 時，參數超過大小限制。
UNKNOWN
錯誤類型不明。

變數

Const IN_PLAYABLES_ENV

IN_PLAYABLES_ENV: boolean
遊戲是否在可播放環境中執行。您可以使用這個值來決定是否要啟用或停用僅適用於遊戲角落的功能。請搭配檢查 ytgame，確保 SDK 確實已載入。
範例
const inPlayablesEnv = typeof ytgame !== "undefined" && ytgame.IN_PLAYABLES_ENV;
 
// An example of where you may want to fork behavior for saving data.
if (ytgame?.IN_PLAYABLES_ENV) {
  ytgame.game.saveData(dataStr);
} else {
  window.localStorage.setItem("SAVE_DATA", dataStr);
}

Const SDK_VERSION

SDK_VERSION: string
YouTube Playables SDK 版本。
範例
// Prints the SDK version to console. Do not do this in production.
console.log(ytgame.SDK_VERSION);

ytgame.SdkError

擴充 Error
YouTube Playables SDK 擲回的錯誤物件。

SdkError 物件是 Error 的子項，並包含額外欄位。
建構函式
constructor
屬性
errorType
錯誤類型。
message
name
stack?

屬性

errorType

errorType: SdkErrorType
錯誤類型。

ytgame.ads

🧪 公開測試版 API：如有變更，恕不另行通知。

與廣告相關的函式和屬性。
函式
requestInterstitialAd
要求顯示插頁式廣告。

函式

requestInterstitialAd

requestInterstitialAd(): Promise<void>
Experimental 要求顯示插頁式廣告。

🧪 公開預覽版 API：如有變更，恕不另行通知。

我們無法保證廣告是否會顯示。
範例
try {
  await ytgame.ads.requestInterstitialAd();
  // Ad request successful, do something else.
} catch (error) {
  // Handle errors, retry logic, etc.
  // Note that error may be undefined.
}
傳回
Promise<void> 在成功要求中解析的承諾，或在失敗要求中拒絕/擲回的承諾。

ytgame.engagement

與玩家參與度相關的函式和屬性。
介面
Content
遊戲傳送至 YouTube 的內容物件。
Score
遊戲傳送至 YouTube 的分數物件。
函式
openYTContent
要求 YouTube 開啟與提供的影片 ID 相對應的內容。
sendScore
將分數傳送至 YouTube。

函式

openYTContent

openYTContent(content: Content): Promise<void>
要求 YouTube 開啟與所提供影片 ID 相對應的內容。

一般來說，這會在網頁的新分頁和行動裝置的迷你播放器中開啟影片。
範例
async function showVideo(videoID: string) {
  try {
    await ytgame.engagement.openYTContent({ id: videoID });
    // Request successful, do something else.
  } catch (error) {
    // Handle errors, retry logic, etc.
    // Note that error may be undefined.
  }
}
參數
content: Content 在 YouTube 上開啟的內容。
傳回
Promise<void> 成功時會解析的 Promise，失敗時會拒絕/擲回 ytgame.SdkError。

sendScore

sendScore(score: Score): Promise<void>
將分數傳送至 YouTube。

分數應代表遊戲中進度的一個維度。如果有多個維度，開發人員必須選擇一個維度以保持一致性。系統會排序分數，並在 YouTube UI 中顯示最高分數，因此任何遊戲內最高分數 UI 都應與透過此 API 傳送的內容一致。
範例
async function onScoreAwarded(score: number) {
  try {
    await ytgame.engagement.sendScore({ value: score });
    // Score sent successfully, do something else.
  } catch (error) {
    // Handle errors, retry logic, etc.
    // Note that error may be undefined.
  }
}
參數
score: Score 要傳送至 YouTube 的評分。
傳回
Promise<void> 成功時會解析的 Promise，失敗時會拒絕/擲回 ytgame.SdkError。

ytgame.engagement.Content

遊戲傳送至 YouTube 的內容物件。
屬性
id
要開啟的影片 ID。

屬性

id

id: string
要開啟的影片 ID。

ytgame.engagement.Score

遊戲傳送至 YouTube 的分數物件。
屬性
value
以整數表示的分數值。

屬性

value

value: number
以整數表示的分數值。分數必須小於或等於最大安全整數。否則系統會拒絕分數。

ytgame.game

與一般遊戲行為相關的函式和屬性。
函式
firstFrameReady
通知 YouTube 遊戲已開始顯示影格。
gameReady
通知 YouTube 遊戲已準備好供玩家互動。
loadData
以序列化字串的形式從 YouTube 載入遊戲資料。
saveData
以序列化字串的形式將遊戲資料儲存到 YouTube。

函式

firstFrameReady

firstFrameReady(): void
通知 YouTube 遊戲已開始顯示影格。

遊戲「必須」MUST呼叫此 API。否則，系統不會向使用者顯示遊戲。 firstFrameReady() MUST在 gameReady() 之前呼叫。
範例
function onGameInitialized() {
  ytgame.game.firstFrameReady();
}

gameReady

gameReady(): void
通知 YouTube 遊戲已準備好供玩家互動。

遊戲在可互動時，MUST呼叫此 API。遊戲在載入畫面仍顯示時，不得呼叫此 API。否則遊戲會無法通過 YouTube 認證程序。
範例
function onGameInteractable() {
  ytgame.game.gameReady();
}

loadData

loadData(): Promise<string>
以序列化字串的形式從 YouTube 載入遊戲資料。

遊戲必須處理字串和內部格式之間的任何剖析作業。
範例
async function gameSetup() {
  try {
    const data = await ytgame.game.loadData();
    // Load succeeded, do something with data.
  } catch (error) {
    // Handle errors, retry logic, etc.
    // Note that error may be undefined.
  }
}
傳回
Promise<string> 載入成功時會完成的 Promise，失敗時會拒絕使用 ytgame.SdkError。

saveData

saveData(data: string): Promise<void>
以序列化字串的形式將遊戲資料儲存到 YouTube。

字串「必須」是有效且格式正確的 UTF-16 字串，且大小不得超過 3 MiB。遊戲「必須」處理字串與內部格式之間的任何剖析作業。如有需要，請使用 String.isWellFormed() 檢查字串是否格式正確。
範例
async function saveGame() {
  try {
    ytgame.game.saveData(JSON.stringify(gameSave));
    // Save succeeded.
  } catch (error) {
    // Handle errors, retry logic, etc.
    // Note that error may be undefined.
  }
}
參數
data: string
傳回
Promise<void> 在儲存成功時解析的 Promise，並在失敗時拒絕使用 ytgame.SdkError。

ytgame.health

與遊戲健康相關的函式和屬性。
函式
logError
將錯誤記錄到 YouTube。
logWarning
向 YouTube 記錄警告。

函式

logError

logError(): void
將錯誤記錄到 YouTube。

注意：這個 API 是盡力而為且有速率限制，可能會導致資料遺失。
範例
function onError() {
  ytgame.health.logError();
}

logWarning

logWarning(): void
將警告記錄到 YouTube。

注意：這個 API 是盡力而為且有速率限制，可能會導致資料遺失。
範例
function onWarning() {
  ytgame.health.logWarning();
}

ytgame.system

與 YouTube 系統相關的函式和屬性。
函式
getLanguage
以 BCP-47 語言標記的形式，傳回使用者 YouTube 設定中設定的語言。
isAudioEnabled
傳回 YouTube 設定中是否已啟用遊戲音訊。
onAudioEnabledChange
在 YouTube 觸發音訊設定變更事件時，設定要觸發的回呼。
onPause
設定回呼，在 YouTube 觸發暫停遊戲事件時觸發。
onResume
在 YouTube 觸發繼續遊戲事件時，設定要觸發的回呼。

函式

getLanguage

getLanguage(): Promise<string>
以 BCP-47 語言代碼的形式，傳回使用者在 YouTube 設定中設定的語言。

請勿使用其他函式判斷使用者的語言或語言代碼，或將其語言偏好設定儲存在雲端儲存空間中。請改用這個函式，確保 YouTube 上的使用者體驗一致。
範例
const localeTag = await ytgame.system.getLanguage();
// `localeTag` is now set to something like "en-US" or "es-419".
傳回
Promise<string> 當取得語言成功時，此承諾會完成，如果失敗，則會拒絕使用 ytgame.SdkError。

isAudioEnabled

isAudioEnabled(): boolean
傳回 YouTube 設定中是否已啟用遊戲音訊。

遊戲「應」使用此值來初始化遊戲音訊狀態。
範例
function initGameSound() {
  if (ytgame.system.isAudioEnabled()) {
    // Enable game audio.
  } else {
    // Disable game audio.
  }
}
傳回
boolean 布林值，表示是否已啟用音訊。

onAudioEnabledChange

onAudioEnabledChange(callback: ((isAudioEnabled: boolean) => void)): (() => void)
設定回呼，在 YouTube 觸發音訊設定變更事件時觸發。

遊戲「必須」MUST使用這個 API 更新遊戲音訊狀態。
範例
ytgame.system.onAudioEnabledChange((isAudioEnabled) => {
  if (isAudioEnabled) {
    // Enable game audio.
  } else {
    // Disable game audio.
  }
});
參數
callback: ((isAudioEnabled: boolean) => void) 要觸發的回呼函式。
傳回
(() => void) 用於取消設定通常未使用的回呼的函式。

onPause

onPause(callback: (() => void)): (() => void)
設定回呼，在 YouTube 觸發暫停遊戲事件時觸發。遊戲在任何狀態遭到淘汰前，都有短暫的時間可儲存該狀態。

onPause 會在所有類型的暫停期間呼叫，包括使用者退出遊戲時。我們無法保證遊戲一定會恢復。
範例
ytgame.system.onPause(() => {
  pauseGame();
});

function pauseGame() {
  // Logic to pause game state.
}
參數
callback: (() => void) 要觸發的回呼函式。
傳回
(() => void) 用於取消設定通常未使用的回呼的函式。

onResume

onResume(callback: (() => void)): (() => void)
設定在 YouTube 觸發繼續遊戲事件時，要觸發的回呼。

系統無法保證在暫停後會繼續遊戲。
範例
ytgame.system.onResume(() => {
  resumeGame();
});

function resumeGame() {
  // Logic to resume game state.
}
參數
callback: (() => void) 要觸發的回呼函式。
傳回
(() => void) 用於取消設定通常未使用的回呼的函式。