YouTube ゲームルーム SDK リファレンス

ytgame

YouTube Playables SDK の最上位の名前空間。

これは、現在のウィンドウのグローバル スコープの変数です。この変数はオーバーライドしてはなりません。
名前空間
ads
広告に関連する関数とプロパティ。
engagement
プレーヤーのエンゲージメントに関連する関数とプロパティ。
game
一般的なゲームの動作に関連する関数とプロパティ。
health
ゲームの健全性に関連する関数とプロパティ。
system
YouTube システムに関連する関数とプロパティ。
列挙型
SdkErrorType
YouTube ゲームルーム SDK がスローするエラーの種類。
クラス
SdkError
YouTube ゲームルーム SDK がスローするエラー オブジェクト。
変数
IN_PLAYABLES_ENV
ゲームがゲームルーム環境内で実行されているかどうか。
SDK_VERSION
YouTube ゲームルーム SDK のバージョン。
関連情報

列挙型

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 Playables 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。

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 を読み取り可能にしたり、UUID にしたりできます。これを、特定の報酬のゲームコードにハードコードされた ID として含めることができます。ID を提供することと、ユーザーデータを含まないことのみが要件です。次に例を示します。
  • 100-coins-reward-12 - 「100 枚のコイン」
  • 7defcfa2-4312-4893-a13a-a84e0c47a4df - 「3 ライフ」
  • 121b001a-0c25-4289-88f6-58e3620d938f - 「レベルをスキップ」
戻り値
Promise<boolean> リクエストが成功した場合に解決される Promise。ユーザーが報酬を受け取る条件を満たしている場合は値が true、満たしていない場合は false になります。リクエストが失敗した場合は、Promise が拒否されるか例外がスローされます。

ytgame.engagement

プレーヤーのエンゲージメントに関連する関数とプロパティ。
列挙型
ContentType
コンテンツの可能なタイプ。
インターフェース
Content
ゲームが YouTube に送信するコンテンツ オブジェクト。
Score
ゲームが YouTube に送信するスコア オブジェクト。
関数
openYTContent
指定されたコンテンツ ID に対応するコンテンツを開くよう YouTube にリクエストします。
sendScore
スコアを YouTube に送信します。

列挙型

Const ContentType

ContentType
コンテンツの可能なタイプ。
列挙型メンバー
PLAYABLE
YouTube ゲームルーム。
VIDEO
YouTube 動画。

関数

openYTContent

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

通常、ウェブの新しいタブでコンテンツが開きます。モバイルでは、動画はミニプレーヤーで開き、現在開いているゲームルームのゲームが置き換えられます。
例
// 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> 成功した場合は解決し、失敗した場合は 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 に送信するコンテンツ オブジェクト。
プロパティ
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> 読み込みが成功したときに完了し、失敗したときに 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>
BCP-47 言語タグの形式で、ユーザーの YouTube 設定で設定されている言語を返します。

ユーザーの言語や地域を特定したり、言語設定をクラウド保存に保存したりするために、他の関数を使用しないでください。代わりに、この関数を使用して、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) 通常は使用されないコールバックを解除する関数。