YouTube 游戏大本营 SDK 参考文档

ytgame

YouTube 游戏大本营 SDK 的顶级命名空间。

这是当前窗口中的全局范围变量。您不得替换此变量。

命名空间
`ads`	🧪 公开预览版 API：如有变更，恕不另行通知。
`engagement`	与玩家互动相关的函数和属性。
`game`	与通用游戏行为相关的函数和属性。
`health`	与游戏健康度相关的函数和属性。
`system`	与 YouTube 系统相关的函数和属性。

枚举
`SdkErrorType`	YouTube 游戏大本营 SDK 抛出的错误类型。

类
`SdkError`	YouTube 游戏大本营 SDK 抛出的错误对象。

变量
`IN_PLAYABLES_ENV`	游戏是否在游戏大本营环境中运行。
`SDK_VERSION`	YouTube 游戏大本营 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

🧪 公开预览版 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，在请求成功时解析，在请求不成功时拒绝/抛出。

requestRewardedAd

requestRewardedAd(rewardId: string): Promise<boolean>

Experimental 请求展示特定奖励类型的激励广告。

🧪 公开预览版 API：可能会在不另行通知的情况下发生更改。

不保证广告是否已展示。

示例

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。例如： 21403813-2e22-4316-a8b2-7d4f52a6f6fb - "100 金币" 7defcfa2-4312-4893-a13a-a84e0c47a4df -“3 条命” 121b001a-0c25-4289-88f6-58e3620d938f -“跳过关卡”

返回
`Promise<boolean>`	一个 Promise，如果用户满足获得奖励的条件，则在请求成功时解析为 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，在成功时解析，在失败时拒绝/抛出 `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 设置中设置的语言。

请勿使用其他 Functions 来确定用户的语言或语言区域，也不要将用户的语言偏好设置存储在云端存档中。请改用此函数，以确保用户在整个 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

函数

sendScore

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