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
要求顯示插頁式廣告。
requestRewardedAd
要求顯示特定獎勵類型的獎勵廣告。

函式

requestInterstitialAd

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

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

不保證廣告是否已顯示。請勿使用這個 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> 如果要求成功，Promise 會解析；如果要求失敗，Promise 則會拒絕/擲回。

requestRewardedAd

requestRewardedAd(rewardId: string): Promise<boolean>
Experimental 要求顯示特定獎勵類型的獎勵廣告。

🧪 PUBLIC PREVIEW API: SUBJECT TO CHANGE WITHOUT NOTICE.

Makes no guarantees about whether the ad was shown.
範例
try {
  const isRewardEarned = await ytgame.ads.requestRewardedAd("21403813-2e22-4316-a8b2-7d4f52a6f6fb");
  // Handle reward being earned or not.
} catch (error) {
  // Handle errors, retry logic, etc.
  // Note that error may be undefined.
}
參數
rewardId: string 必填。可明確識別可領取獎勵類型的 ID。 每種獎勵類型都必須使用專屬 ID，且每次提供該獎勵類型時，都必須重複使用相同 ID。例如：
  • 21403813-2e22-4316-a8b2-7d4f52a6f6fb - "100 coins"
  • 7defcfa2-4312-4893-a13a-a84e0c47a4df - "3 lives"
  • 121b001a-0c25-4289-88f6-58e3620d938f -「略過等級」
傳回
Promise<boolean> 如果使用者符合領取獎勵的條件，則承諾會在要求成功時解析為 true 值；如果使用者不符合條件，則解析為 false 值。如果要求失敗，這個 Promise 會拒絕/擲回。

ytgame.engagement

與玩家參與度相關的函式和屬性。
介面
Score
遊戲傳送至 YouTube 的分數物件。
函式
sendScore
將分數傳送至 YouTube。

函式

sendScore

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

分數應代表遊戲中的某個進度層面。如果有多個維度，開發人員必須選擇其中一個維度，確保一致性。系統會排序分數，並在 YouTube 使用者介面中顯示最高分，因此遊戲內的高分使用者介面應與透過這個 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 會解析；如果失敗，Promise 會拒絕/擲回 ytgame.SdkError。

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> 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> Promise，在取得語言成功時完成，失敗時則會以 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) 取消設定回呼的函式，通常不會使用。