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
指定された動画 ID に対応するコンテンツを開くよう YouTube にリクエストします。
sendScore
スコアを YouTube に送信します。

関数

openYTContent

openYTContent(content: Content): Promise<void>
指定された動画 ID に対応するコンテンツを開くよう YouTube にリクエストします。

通常、ウェブでは新しいタブで、モバイルではミニプレーヤーで動画が開きます。
例
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 で拒否/スローされる Promise。

sendScore

sendScore(score: Score): Promise<void>
スコアを YouTube に送信します。

スコアは、ゲーム内の進行状況の 1 つのディメンションを表す必要があります。ディメンションが複数ある場合は、一貫性を保つために 1 つのディメンションを選択する必要があります。スコアは並べ替えられ、最高スコアが 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 で拒否/スローされる Promise。

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 をMUST。そうでない場合、ゲームはユーザーに表示されません。 firstFrameReady() は gameReady() の前に呼び出す必要があります。MUST
例
function onGameInitialized() {
  ytgame.game.firstFrameReady();
}

gameReady

gameReady(): void
ゲームがプレイヤーが操作できる状態であることを YouTube に通知します。

ゲームが操作可能になったら、この API を呼び出すMUST。読み込み画面が表示されている間は、ゲームがこの 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 で拒否される Promise。

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> 保存が成功すると解決し、失敗すると ytgame.SdkError で拒否される Promise。

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
ユーザーの YouTube 設定で設定されている言語を BCP-47 言語タグの形式で返します。
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> 言語の取得が成功すると完了し、失敗すると ytgame.SdkError で拒否される Promise。

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 を使用してゲーム音声の状態を更新MUST。
例
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) 通常は使用されないコールバックを設定解除する関数。