Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

YouTube 遊戲角落 SDK 參考資料

ytgame

YouTube Playables SDK 的頂層命名空間。

這是目前視窗中的全域範圍變數。您「不得」覆寫這個變數。

命名空間
`ads`	與廣告相關的函式和屬性。
`engagement`	與玩家參與度相關的函式和屬性。
`game`	與一般遊戲行為相關的函式和屬性。
`health`	與遊戲健康狀態相關的函式和屬性。
`system`	與 YouTube 系統相關的函式和屬性。

列舉
`SdkErrorType`	YouTube 遊戲角落 SDK 擲回的錯誤類型。

類別
`SdkError`	YouTube 遊戲角落 SDK 擲回的錯誤物件。

變數
`IN_PLAYABLES_ENV`	遊戲是否在「遊戲角落」環境中執行。
`SDK_VERSION`	YouTube Playables SDK 版本。

另請參閱

https://developers.google.com/youtube/gaming/playables

列舉

`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

與廣告相關的函式和屬性。

函式
`requestInterstitialAd`	要求顯示插頁式廣告。
`requestRewardedAd`	要求顯示特定獎勵類型的獎勵廣告。

函式

requestInterstitialAd

requestInterstitialAd(): Promise<void>

要求顯示插頁式廣告。

不保證廣告是否已顯示。請勿使用這個 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>

要求顯示特定獎勵類型的獎勵廣告。

不保證廣告是否會顯示。

範例

try {
  const isRewardEarned = await ytgame.ads.requestRewardedAd("reward-123");
  // Handle reward being earned or not.
} catch (error) {
  // Handle errors, retry logic, etc.
  // Note that error may be undefined.
}

參數

參數
`rewardId: string`	必填。可明確識別可領取獎勵類型的 ID。每種獎勵類型都必須使用專屬 ID，且每次提供該獎勵類型時，都必須重複使用相同 ID。舉例來說，您可以將 ID 設為可讀取的 ID 或 UUID。您可以在遊戲程式碼中加入這個 ID，做為特定獎勵的硬式編碼 ID。我們只要求您提供 ID，且 ID 不得包含任何使用者資料。例如： 100-coins-reward-12 -「100 枚金幣」 7defcfa2-4312-4893-a13a-a84e0c47a4df - "3 lives" 121b001a-0c25-4289-88f6-58e3620d938f -「略過等級」

rewardId: string

必填。可明確識別可領取獎勵類型的 ID。每種獎勵類型都必須使用專屬 ID，且每次提供該獎勵類型時，都必須重複使用相同 ID。舉例來說，您可以將 ID 設為可讀取的 ID 或 UUID。您可以在遊戲程式碼中加入這個 ID，做為特定獎勵的硬式編碼 ID。我們只要求您提供 ID，且 ID 不得包含任何使用者資料。例如：

100-coins-reward-12 -「100 枚金幣」
7defcfa2-4312-4893-a13a-a84e0c47a4df - "3 lives"
121b001a-0c25-4289-88f6-58e3620d938f -「略過等級」

傳回
`Promise<boolean>`	如果使用者符合領取獎勵的條件，則承諾會在要求成功時解析為 true 值；如果使用者不符合條件，則解析為 false 值。如果要求失敗，這個 Promise 會拒絕/擲回。

ytgame.engagement

與玩家參與度相關的函式和屬性。

列舉
`ContentType`	可能的內容類型。

介面
`Content`	遊戲傳送至 YouTube 的內容物件。
`Score`	遊戲傳送至 YouTube 的分數物件。

函式
`openYTContent`	要求 YouTube 開啟與所提供內容 ID 相對應的內容。
`sendScore`	將得分傳送至 YouTube。

列舉

`Const` ContentType

ContentType

可能的內容類型。

列舉成員
`PLAYABLE`	YouTube 遊戲角落遊戲。
`VIDEO`	YouTube 影片。

函式

openYTContent

openYTContent(content: Content): Promise<void>

要求 YouTube 開啟與所提供內容 ID 相應的內容。

一般來說，這會在網頁的新分頁中開啟內容。在行動裝置上，影片會在迷你播放器中開啟，而可播放內容會取代目前開啟的可播放內容。

範例

// Open a video.
async function showVideo(videoID: string) {
  try {
    await ytgame.engagement.openYTContent({
      id: videoID,
      contentType: ytgame.engagement.ContentType.VIDEO,
    });
    // Request successful, content may have opened.
  } catch (error) {
    // Handle errors, retry logic, etc.
    // Note that error may be undefined.
  }
}

// Open a Playable.
async function openDifferentPlayable(playableID: string) {
  try {
    await ytgame.engagement.openYTContent({
      id: playableID,
      contentType: ytgame.engagement.ContentType.PLAYABLE,
    });
    // Request successful, content may have opened.
    // On mobile, the new Playable will replace the current one.
  } catch (error) {
    // Handle errors, retry logic, etc.
    // Note that error may be undefined.
  }
}

參數
`content: Content`	要在 YouTube 開啟的內容。

傳回
`Promise<void>`	如果成功，Promise 會解析；如果失敗，Promise 會拒絕/擲回 `ytgame.SdkError`。

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.Content

遊戲傳送至 YouTube 的內容物件。

屬性
`contentType?`	要開啟的內容類型。
`id`	要開啟的內容 ID。

屬性

`Optional` contentType

contentType?:
                    ContentType

要開啟的內容類型。應提供此值，但如未提供，系統會假設為 VIDEO。

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

傳回使用者 YouTube 設定中設定的語言，格式為 BCP-47 語言代碼。

請勿使用其他函式判斷使用者的語言或地區，也不要將語言偏好設定儲存在雲端儲存空間。請改用這項函式，確保 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)`	取消設定回呼的函式，通常不會用到。

YouTube 遊戲角落 SDK 參考資料 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

ytgame

列舉

Const SdkErrorType

變數

Const IN_PLAYABLES_ENV

Const SDK_VERSION

ytgame.SdkError

屬性

errorType

ytgame.ads

函式

requestInterstitialAd

requestRewardedAd

ytgame.engagement

列舉

Const ContentType

函式

openYTContent

sendScore

ytgame.engagement.Content

屬性

Optional contentType

id

ytgame.engagement.Score

屬性

value

ytgame.game

函式

firstFrameReady

gameReady

loadData

saveData

ytgame.health

函式

logError

logWarning

ytgame.system

函式

getLanguage

isAudioEnabled

onAudioEnabledChange

onPause

onResume

YouTube 遊戲角落 SDK 參考資料

`Const` SdkErrorType

`Const` IN_PLAYABLES_ENV

`Const` SDK_VERSION

`Const` ContentType

`Optional` contentType