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。

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> ユーザーが報酬を受け取る条件を満たしている場合は true、満たしていない場合は false の値で、リクエストが成功すると解決される Promise。リクエストが失敗すると、Promise は拒否または例外をスローします。

ytgame.engagement

プレーヤーのエンゲージメントに関連する関数とプロパティ。
インターフェース
Score
ゲームが YouTube に送信するスコア オブジェクト。
関数
sendScore
スコアを YouTube に送信します。

関数

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.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> 読み込みが成功したときに完了し、失敗したときに 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 を使用してゲームの音声状態を更新しなければなりません。
例
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) 通常は使用されないコールバックを解除する関数。