YouTube 遊戲角落 SDK 參考資料

ytgame

YouTube 遊戲角落 SDK 的頂層命名空間。

這是目前視窗中的全域範圍變數。您「不得」覆寫這個變數。
命名空間
ads
🧪 PUBLIC PREVIEW API：變更前無須通知。
engagement
與玩家參與度相關的函式和屬性。
game
與一般遊戲行為相關的功能和屬性。
health
與遊戲健康相關的函式和屬性。
system
與 YouTube 系統相關的函式和屬性。
列舉
SdkErrorType
YouTube 遊戲角落 SDK 擲回的錯誤類型。
類別
SdkError
YouTube Playables SDK 擲回的錯誤物件。
變數
IN_PLAYABLES_ENV
遊戲是否在遊戲角落環境中執行。
SDK_VERSION
YouTube 遊戲角落 SDK 版本。
另請參閱

列舉

Const SdkErrorType

SdkErrorType
YouTube 遊戲角落 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 遊戲角落 SDK 版本。
範例
// Prints the SDK version to console. Do not do this in production.
console.log(ytgame.SDK_VERSION);

ytgame.SdkError

擴充 Error
YouTube 遊戲角落 SDK 擲回的錯誤物件。

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

屬性

errorType

errorType: SdkErrorType
錯誤的類型。

ytgame.ads

🧪 PUBLIC PREVIEW API：變更時不另行通知。

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

函式

requestInterstitialAd

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

🧪 PUBLIC PREVIEW 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> 會在成功時解析，且失敗時以 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> 會在成功時解析，且失敗時以 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 遊戲已開始顯示影格。

遊戲 「必須」呼叫這個 API。否則，使用者就不會看到遊戲。 firstFrameReady() 必須在 gameReady() 之前呼叫。
範例
function onGameInitialized() {
  ytgame.game.firstFrameReady();
}

gameReady

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

遊戲在能夠互動時，「必須」呼叫這個 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> 載入成功時完成的承諾，且失敗時會以 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>
傳回使用者在 YouTube 設定中設定的語言，格式為 BCP-47 語言標記。
範例
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 觸發音訊設定變更事件時觸發的回呼。

遊戲「必須」使用這個 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) 用來取消設定通常未使用的回呼的函式。