YouTube 游戏大本营 SDK 参考文档

ytgame

YouTube Playables SDK 的顶级命名空间。

这是当前窗口中的一个全局范围变量。您不得替换此变量。
命名空间
ads
🧪 公开预览版 API：如有变更，恕不另行通知。
engagement
与玩家互动相关的函数和属性。
game
与通用游戏行为相关的函数和属性。
health
与游戏健康度相关的函数和属性。
system
与 YouTube 系统相关的函数和属性。
枚举
SdkErrorType
YouTube Playables SDK 抛出的错误类型。
类
SdkError
YouTube Playables SDK 抛出的错误对象。
变量
IN_PLAYABLES_ENV
游戏是否在 Playables 环境中运行。
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
游戏是否在 Playables 环境中运行。您可以使用此属性来确定是否启用或停用仅在游戏大本营中可用的功能。将此检查与检查 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> 一个 promise，会在请求成功时解析，或在请求失败时拒绝/抛出。

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 界面中显示最高得分，因此游戏中的任何最高得分界面都应与通过此 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()，然后再调用 gameReady()。MUST
示例
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> 一个 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 触发音频设置更改事件时触发的回调。

游戏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) 用于取消设置通常不使用的回调的函数。