Referenz zum YouTube Playables SDK

ytgame

Der Namespace der obersten Ebene für das YouTube Playables SDK.

Dies ist eine global definierte Variable im aktuellen Fenster. Sie DÜRFEN diese Variable nicht überschreiben.

Namespaces
`ads`	🧪 API FÜR DIE ÖFFENTLICHE VORSCHAU: KANN OHNE VORHERIGE BENACHRICHTIGUNG GEÄNDERT WERDEN.
`engagement`	Die Funktionen und Eigenschaften im Zusammenhang mit der Spielerinteraktion.
`game`	Die Funktionen und Eigenschaften, die sich auf generische Spielverhaltensweisen beziehen.
`health`	Die Funktionen und Eigenschaften, die sich auf die Gesundheit des Spiels beziehen.
`system`	Die Funktionen und Eigenschaften, die sich auf das YouTube-System beziehen.

Aufzählungen
`SdkErrorType`	Die Arten von Fehlern, die das YouTube Playables SDK ausgibt.

Klassen
`SdkError`	Das Fehlerobjekt, das vom YouTube Playables SDK ausgegeben wird.

Variablen
`IN_PLAYABLES_ENV`	Gibt an, ob das Spiel in der Playables-Umgebung ausgeführt wird.
`SDK_VERSION`	Die YouTube Playables SDK-Version.

Weitere Informationen

https://developers.google.com/youtube/gaming/playables

Aufzählungen

`Const` SdkErrorType

SdkErrorType

Die Arten von Fehlern, die das YouTube Playables SDK ausgibt.

Enumerationsmitglieder
`API_UNAVAILABLE`	Die API war vorübergehend nicht verfügbar. Bitte Spieler, es später noch einmal zu versuchen, wenn sie sich in einem kritischen Ablauf befinden.
`INVALID_PARAMS`	Die API wurde mit ungültigen Parametern aufgerufen.
`SIZE_LIMIT_EXCEEDED`	Die API wurde mit Parametern aufgerufen, die das Größenlimit überschreiten.
`UNKNOWN`	Der Fehlertyp ist unbekannt.

Variablen

`Const` IN_PLAYABLES_ENV

IN_PLAYABLES_ENV: boolean

Gibt an, ob das Spiel in der Playables-Umgebung ausgeführt wird. Damit können Sie festlegen, ob Funktionen, die nur in Playables verfügbar sind, aktiviert oder deaktiviert werden sollen. Kombinieren Sie diese Prüfung mit der Prüfung auf ytgame, um sicherzustellen, dass das SDK tatsächlich geladen wird.

Beispiel

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

Die YouTube Playables SDK-Version.

Beispiel

// Prints the SDK version to console. Do not do this in production.
console.log(ytgame.SDK_VERSION);

ytgame.SdkError

Erweitert Error

Das Fehlerobjekt, das vom YouTube Playables SDK ausgegeben wird.

Das Objekt SdkError ist ein untergeordnetes Element von Error und enthält ein zusätzliches Feld.

Konstruktoren
`constructor`

Attribute
`errorType`	Die Art des Fehlers.
`message`
`name`
`stack?`

Attribute

errorType

errorType:
                  SdkErrorType

Die Art des Fehlers.

ytgame.ads

🧪 API FÜR DIE ÖFFENTLICHE VORSCHAU: KANN OHNE VORANKÜNDIGUNG GEÄNDERT WERDEN.

Die Funktionen und Eigenschaften im Zusammenhang mit Anzeigen.

Funktionen
`requestInterstitialAd`	Fordert die Auslieferung einer Interstitial-Anzeige an.
`requestRewardedAd`	Fordert an, dass eine Anzeige mit Prämie für einen bestimmten Prämientyp ausgeliefert wird.

Funktionen

requestInterstitialAd

requestInterstitialAd(): Promise<void>

Experimental Fordert an, dass eine Interstitial-Anzeige ausgeliefert wird.

🧪 API IN DER ÖFFENTLICHEN VORSCHAU: KANN OHNE VORANKÜNDIGUNG GEÄNDERT WERDEN.

Es wird nicht garantiert, dass die Anzeige ausgeliefert wurde. Verwenden Sie diese API nicht, um Spieler für das Ansehen einer Anzeige zu belohnen.

Beispiel

try {
  await ytgame.ads.requestInterstitialAd();
  // Ad request successful, do something else.
} catch (error) {
  // Handle errors, retry logic, etc.
  // Note that error may be undefined.
}

Ausgabe
`Promise<void>`	Ein Promise, das bei einer erfolgreichen Anfrage aufgelöst wird oder bei einer nicht erfolgreichen Anfrage abgelehnt oder ausgelöst wird.

requestRewardedAd

requestRewardedAd(rewardId: string): Promise<boolean>

Experimental Fordert an, dass eine Anzeige mit Prämie für einen bestimmten Prämientyp ausgeliefert wird.

🧪 API IN DER ÖFFENTLICHEN VORSCHAU: KANN OHNE VORANKÜNDIGUNG GEÄNDERT WERDEN.

Es wird nicht garantiert, dass die Anzeige ausgeliefert wird.

Beispiel

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.
}

Parameter

Parameter
`rewardId: string`	Erforderlich. Eine Kennung, die den einlösbaren Prämietyp eindeutig identifiziert. Sie müssen für jede Art von Prämie eine eindeutige ID verwenden und dieselbe ID jedes Mal wiederverwenden, wenn diese Art von Prämie angeboten wird. Beispiel: 21403813-2e22-4316-a8b2-7d4f52a6f6fb – „100 Coins“ 7defcfa2-4312-4893-a13a-a84e0c47a4df – „3 Lives“ 121b001a-0c25-4289-88f6-58e3620d938f – „Skip level“ (Level überspringen)

rewardId: string

Erforderlich. Eine Kennung, die den einlösbaren Prämietyp eindeutig identifiziert. Sie müssen für jede Art von Prämie eine eindeutige ID verwenden und dieselbe ID jedes Mal wiederverwenden, wenn diese Art von Prämie angeboten wird. Beispiel:

21403813-2e22-4316-a8b2-7d4f52a6f6fb – „100 Coins“
7defcfa2-4312-4893-a13a-a84e0c47a4df – „3 Lives“
121b001a-0c25-4289-88f6-58e3620d938f – „Skip level“ (Level überspringen)

Ausgabe
`Promise<boolean>`	Ein Promise, das bei einer erfolgreichen Anfrage mit dem Wert „true“ aufgelöst wird, wenn der Nutzer die Bedingungen für den Erhalt einer Prämie erfüllt hat, oder mit dem Wert „false“, wenn dies nicht der Fall ist. Das Promise wird bei einer nicht erfolgreichen Anfrage abgelehnt oder es wird ein Fehler ausgegeben.

ytgame.engagement

Die Funktionen und Eigenschaften im Zusammenhang mit der Spielerinteraktion.

Schnittstellen
`Score`	Das Score-Objekt, das das Spiel an YouTube sendet.

Funktionen
`sendScore`	Es wird eine Punktzahl an YouTube gesendet.

Funktionen

sendScore

sendScore(score: Score): Promise<void>

Sendet einen Wert an YouTube.

Der Wert sollte eine Dimension des Fortschritts im Spiel darstellen. Wenn es mehrere Dimensionen gibt, muss der Entwickler eine Dimension auswählen, die konsistent ist. Die Punktzahlen werden sortiert und die höchste Punktzahl wird in der YouTube-Benutzeroberfläche angezeigt. Die Benutzeroberfläche für die höchste Punktzahl im Spiel sollte also mit den über diese API gesendeten Daten übereinstimmen.

Beispiel

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.
  }
}

Parameter
`score: Score`	die Punktzahl, die an YouTube gesendet werden soll.

Ausgabe
`Promise<void>`	Ein Promise, das bei Erfolg aufgelöst und bei einem Fehler mit einem `ytgame.SdkError` abgelehnt oder ausgelöst wird.

ytgame.engagement.Score

Das Score-Objekt, das das Spiel an YouTube sendet.

Attribute
`value`	Der als Ganzzahl ausgedrückte Score-Wert.

Attribute

Wert

value: number

Der als Ganzzahl ausgedrückte Score-Wert. Der Wert muss kleiner oder gleich der maximalen sicheren Ganzzahl sein. Andernfalls wird die Punktzahl abgelehnt.

ytgame.game

Die Funktionen und Eigenschaften, die sich auf generische Spielverhaltensweisen beziehen.

Funktionen
`firstFrameReady`	Benachrichtigt YouTube, dass das Spiel mit der Anzeige von Frames begonnen hat.
`gameReady`	Benachrichtigt YouTube, dass das Spiel für die Interaktion mit Spielern bereit ist.
`loadData`	Lädt Spieldaten von YouTube in Form eines serialisierten Strings.
`saveData`	Speichert Spieldaten in YouTube in Form eines serialisierten Strings.

Funktionen

firstFrameReady

firstFrameReady(): void

Benachrichtigt YouTube, dass das Spiel mit der Anzeige von Frames begonnen hat.

Das Spiel MUSS diese API aufrufen. Andernfalls wird das Spiel Nutzern nicht angezeigt. firstFrameReady() MUSS vor gameReady() aufgerufen werden.

Beispiel

function onGameInitialized() {
  ytgame.game.firstFrameReady();
}

gameReady

gameReady(): void

Benachrichtigt YouTube, dass das Spiel für die Interaktion mit Spielern bereit ist.

Das Spiel MUSS diese API aufrufen, wenn es interaktiv ist. Das Spiel DARF NICHT diese API aufrufen, wenn noch ein Ladebildschirm angezeigt wird. Andernfalls besteht das Spiel die YouTube-Zertifizierung nicht.

Beispiel

function onGameInteractable() {
  ytgame.game.gameReady();
}

loadData

loadData(): Promise<string>

Lädt Spieldaten von YouTube in Form eines serialisierten Strings.

Das Spiel muss das Parsen zwischen dem String und einem internen Format übernehmen.

Beispiel

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.
  }
}

Ausgabe
`Promise<string>`	Ein Promise, das abgeschlossen wird, wenn das Laden erfolgreich war, und mit einem `ytgame.SdkError` abgelehnt wird, wenn es fehlgeschlagen ist.

saveData

saveData(data: string): Promise<void>

Speichert Spieldaten in YouTube in Form eines serialisierten Strings.

Der String muss ein gültiger, wohlgeformter UTF-16-String mit einer maximalen Größe von 3 MiB sein. Das Spiel muss das Parsen zwischen dem String und einem internen Format übernehmen. Verwenden Sie bei Bedarf String.isWellFormed(), um zu prüfen, ob der String wohlgeformt ist.

Beispiel

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.
  }
}

Parameter
`data: string`

Ausgabe
`Promise<void>`	Ein Promise, das aufgelöst wird, wenn das Speichern erfolgreich war, und mit einem `ytgame.SdkError` abgelehnt wird, wenn es fehlgeschlagen ist.

ytgame.health

Die Funktionen und Eigenschaften, die sich auf die Gesundheit des Spiels beziehen.

Funktionen
`logError`	Es wird ein Fehler an YouTube gemeldet.
`logWarning`	Es wird eine Warnung an YouTube gesendet.

Funktionen

logError

logError(): void

Es wird ein Fehler an YouTube protokolliert.

Hinweis:Diese API ist „Best Effort“ und ratenbegrenzt, was zu Datenverlusten führen kann.

Beispiel

function onError() {
  ytgame.health.logError();
}

logWarning

logWarning(): void

Es wird eine Warnung an YouTube gesendet.

Hinweis:Diese API ist „Best Effort“ und ratenbeschränkt, was zu Datenverlusten führen kann.

Beispiel

function onWarning() {
  ytgame.health.logWarning();
}

ytgame.system

Die Funktionen und Eigenschaften, die sich auf das YouTube-System beziehen.

Funktionen
`getLanguage`	Gibt die Sprache zurück, die in den YouTube-Einstellungen des Nutzers festgelegt ist, in Form eines BCP-47-Sprachentags.
`isAudioEnabled`	Gibt zurück, ob der Spiel-Audio in den YouTube-Einstellungen aktiviert ist.
`onAudioEnabledChange`	Legt einen Callback fest, der ausgelöst wird, wenn das Ereignis „Audioeinstellungen ändern“ von YouTube ausgelöst wird.
`onPause`	Legt einen Callback fest, der ausgelöst wird, wenn ein Ereignis zum Pausieren des Spiels von YouTube ausgelöst wird.
`onResume`	Legt einen Callback fest, der ausgelöst wird, wenn ein Ereignis zum Fortsetzen des Spiels von YouTube ausgelöst wird.

Funktionen

getLanguage

getLanguage(): Promise<string>

Gibt die Sprache zurück, die in den YouTube-Einstellungen des Nutzers festgelegt ist, in Form eines BCP-47-Sprachtags.

Verwenden Sie keine anderen Funktionen, um die Sprache oder das Gebietsschema des Nutzers zu ermitteln, und speichern Sie die Spracheinstellung des Nutzers nicht in der Cloud-Speicherung. Verwenden Sie stattdessen diese Funktion, um für eine einheitliche Nutzererfahrung auf YouTube zu sorgen.

Beispiel

const localeTag = await ytgame.system.getLanguage();
// `localeTag` is now set to something like "en-US" or "es-419".

Ausgabe
`Promise<string>`	Ein Promise, das abgeschlossen wird, wenn die Sprache abgerufen wurde, und das bei einem Fehler mit einem `ytgame.SdkError` abgelehnt wird.

isAudioEnabled

isAudioEnabled(): boolean

Gibt zurück, ob die Spielaudio in den YouTube-Einstellungen aktiviert ist.

Das Spiel SOLLTE diese Einstellung verwenden, um den Status der Spielaudio zu initialisieren.

Beispiel

function initGameSound() {
  if (ytgame.system.isAudioEnabled()) {
    // Enable game audio.
  } else {
    // Disable game audio.
  }
}

Ausgabe
`boolean`	Ein boolescher Wert, der angibt, ob die Audioausgabe aktiviert ist.

onAudioEnabledChange

onAudioEnabledChange(callback: ((isAudioEnabled: boolean) => void)): (() => void)

Legt einen Callback fest, der ausgelöst wird, wenn das Ereignis „Audioeinstellungen ändern“ von YouTube ausgelöst wird.

Das Spiel MUSS diese API verwenden, um den Audiostatus des Spiels zu aktualisieren.

Beispiel

ytgame.system.onAudioEnabledChange((isAudioEnabled) => {
  if (isAudioEnabled) {
    // Enable game audio.
  } else {
    // Disable game audio.
  }
});

Parameter
`callback: ((isAudioEnabled: boolean) => void)`	Die Callback-Funktion, die ausgelöst werden soll.

Ausgabe
`(() => void)`	Eine Funktion zum Aufheben der Festlegung des Callbacks, die normalerweise nicht verwendet wird.

onPause

onPause(callback: (() => void)): (() => void)

Legt einen Callback fest, der ausgelöst wird, wenn ein Ereignis zum Pausieren des Spiels von YouTube ausgelöst wird. Das Spiel hat ein kurzes Zeitfenster, um den Status zu speichern, bevor es entfernt wird.

onPause wird bei allen Arten von Pausen aufgerufen, auch wenn der Nutzer das Spiel beendet. Es gibt keine Garantie dafür, dass das Spiel fortgesetzt wird.

Beispiel

ytgame.system.onPause(() => {
  pauseGame();
});

function pauseGame() {
  // Logic to pause game state.
}

Parameter
`callback: (() => void)`	Die Callback-Funktion, die ausgelöst werden soll.

Ausgabe
`(() => void)`	Eine Funktion zum Aufheben der Festlegung des Callbacks, die normalerweise nicht verwendet wird.

onResume

onResume(callback: (() => void)): (() => void)

Legt einen Callback fest, der ausgelöst wird, wenn ein Ereignis zum Fortsetzen des Spiels von YouTube ausgelöst wird.

Nach dem Pausieren wird das Spiel nicht garantiert fortgesetzt.

Beispiel

ytgame.system.onResume(() => {
  resumeGame();
});

function resumeGame() {
  // Logic to resume game state.
}

Parameter
`callback: (() => void)`	Die Callback-Funktion, die ausgelöst werden soll.

Ausgabe
`(() => void)`	Eine Funktion zum Aufheben der Festlegung des Callbacks, die normalerweise nicht verwendet wird.

Referenz zum YouTube Playables SDK Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

ytgame

Aufzählungen

Const SdkErrorType

Variablen

Const IN_PLAYABLES_ENV

Const SDK_VERSION

ytgame.SdkError

Attribute

errorType

ytgame.ads

Funktionen

requestInterstitialAd

requestRewardedAd

ytgame.engagement

Funktionen

sendScore

ytgame.engagement.Score

Attribute

Wert

ytgame.game

Funktionen

firstFrameReady

gameReady

loadData

saveData

ytgame.health

Funktionen

logError

logWarning

ytgame.system

Funktionen

getLanguage

isAudioEnabled

onAudioEnabledChange

onPause

onResume

Referenz zum YouTube Playables SDK

`Const` SdkErrorType

`Const` IN_PLAYABLES_ENV

`Const` SDK_VERSION