Cette page a été traduite par l'API Cloud Translation.

Documentation de référence sur le SDK Jeux intégrés YouTube

ytgame

Espace de noms de premier niveau pour le SDK YouTube Playables.

Il s'agit d'une variable de portée globale dans la fenêtre actuelle. Vous NE DEVEZ PAS remplacer cette variable.

Espaces de noms
`ads`	🧪 API EN PRÉVUE PUBLIQUE : SUJETTE À MODIFICATION SANS PRÉAVIS.
`engagement`	Fonctions et propriétés liées à l'engagement des joueurs.
`game`	Fonctions et propriétés liées aux comportements de jeu génériques.
`health`	Fonctions et propriétés liées à la santé du jeu.
`system`	Fonctions et propriétés liées au système YouTube

Énumérations
`SdkErrorType`	Types d'erreurs générés par le SDK YouTube Playables.

Classes
`SdkError`	Objet d'erreur généré par le SDK YouTube Playables.

Variables
`IN_PLAYABLES_ENV`	Indique si le jeu s'exécute ou non dans l'environnement Playables.
`SDK_VERSION`	Version du SDK YouTube Playables.

Voir aussi

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

Énumérations

`Const` SdkErrorType

SdkErrorType

Types d'erreurs générés par le SDK YouTube Playables.

Membres de l'énumération
`API_UNAVAILABLE`	L'API était temporairement indisponible. Demandez aux joueurs de réessayer plus tard s'ils se trouvent dans un flux critique.
`INVALID_PARAMS`	L'API a été appelée avec des paramètres non valides.
`SIZE_LIMIT_EXCEEDED`	L'API a été appelée avec des paramètres dépassant la limite de taille.
`UNKNOWN`	Le type d'erreur est inconnu.

Variables

`Const` IN_PLAYABLES_ENV

IN_PLAYABLES_ENV: boolean

Indique si le jeu s'exécute ou non dans l'environnement Playables. Vous pouvez l'utiliser pour déterminer si vous devez activer ou désactiver les fonctionnalités qui ne sont disponibles que dans les jeux intégrés. Combinez cette vérification à la recherche de ytgame pour vous assurer que le SDK est bien chargé.

Exemple

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

Version du SDK YouTube Playables.

Exemple

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

ytgame.SdkError

Étend Error

Objet d'erreur généré par le SDK YouTube Playables.

L'objet SdkError est un enfant de Error et contient un champ supplémentaire.

Constructeurs
`constructor`

Propriétés
`errorType`	Type d'erreur.
`message`
`name`
`stack?`

Propriétés

errorType

errorType:
                  SdkErrorType

Type d'erreur.

ytgame.ads

🧪 API PRÉVUE PUBLIQUE : SUJETTE À MODIFICATION SANS PRÉAVIS.

Fonctions et propriétés liées aux annonces.

Fonctions
`requestInterstitialAd`	Demande la diffusion d'une annonce interstitielle.

Fonctions

requestInterstitialAd

requestInterstitialAd(): Promise<void>

Experimental Demande la diffusion d'une annonce interstitielle.

🧪 API PRÉVUE PUBLIQUE : SUJETTE À MODIFICATION SANS PRÉAVIS.

Ne garantit pas que l'annonce a été diffusée.

Exemple

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

Renvoie
`Promise<void>`	une promesse qui se résout en cas de requête réussie ou qui refuse/jette en cas de requête non réussie.

ytgame.engagement

Fonctions et propriétés liées à l'engagement des joueurs.

Interfaces
`Content`	Objet de contenu envoyé par le jeu à YouTube.
`Score`	Objet de score que le jeu envoie à YouTube.

Fonctions
`openYTContent`	Demande à YouTube d'ouvrir le contenu correspondant à l'ID vidéo fourni.
`sendScore`	Envoie un score à YouTube.

Fonctions

openYTContent

openYTContent(content: Content): Promise<void>

Demande à YouTube d'ouvrir le contenu correspondant à l'ID vidéo fourni.

En général, la vidéo s'ouvre dans un nouvel onglet sur le Web et dans le minilecteur sur mobile.

Exemple

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

Paramètres
`content: Content`	le contenu à ouvrir sur YouTube.

Renvoie
`Promise<void>`	Une promesse qui se résout en cas de réussite et qui rejette/génère une exception avec un `ytgame.SdkError` en cas d'échec.

sendScore

sendScore(score: Score): Promise<void>

Envoie un score à YouTube.

Le score doit représenter une dimension de la progression dans le jeu. Si plusieurs dimensions sont définies, le développeur doit en choisir une pour assurer la cohérence. Les scores seront triés et le score le plus élevé s'affichera dans l'interface utilisateur de YouTube. Par conséquent, toute interface utilisateur de meilleur score dans le jeu doit correspondre à ce qui est envoyé via cette API.

Exemple

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

Paramètres
`score: Score`	le score à envoyer à YouTube.

Renvoie
`Promise<void>`	Une promesse qui se résout en cas de réussite et qui rejette/génère une exception avec un `ytgame.SdkError` en cas d'échec.

ytgame.engagement.Content

Objet de contenu envoyé par le jeu à YouTube.

Propriétés
`id`	ID de la vidéo que nous souhaitons ouvrir.

Propriétés

id

id: string

ID de la vidéo que nous souhaitons ouvrir.

ytgame.engagement.Score

Objet de score que le jeu envoie à YouTube.

Propriétés
`value`	Valeur du score exprimée sous forme d'entier.

Propriétés

value

value: number

Valeur du score exprimée sous forme d'entier. Le score doit être inférieur ou égal à l'entier maximal sécurisé. Sinon, le score sera rejeté.

ytgame.game

Fonctions et propriétés liées aux comportements de jeu génériques.

Fonctions
`firstFrameReady`	Informe YouTube que le jeu a commencé à afficher des frames.
`gameReady`	Informe YouTube que le jeu est prêt à interagir avec les joueurs.
`loadData`	Charge les données de jeu à partir de YouTube sous la forme d'une chaîne sérialisée.
`saveData`	Enregistre les données de jeu dans YouTube sous la forme d'une chaîne sérialisée.

Fonctions

firstFrameReady

firstFrameReady(): void

Informe YouTube que le jeu a commencé à afficher des images.

Le jeu MUST appeler cette API. Dans le cas contraire, le jeu ne s'affiche pas auprès des utilisateurs. firstFrameReady() MUST être appelé avant gameReady().

Exemple

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

gameReady

gameReady(): void

Informe YouTube que le jeu est prêt à interagir avec les joueurs.

Le jeu MUST appeler cette API lorsqu'il est interactif. Le jeu NE DOIT PAS appeler cette API lorsqu'un écran de chargement est toujours affiché. Sinon, le jeu échoue au processus de certification YouTube.

Exemple

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

loadData

loadData(): Promise<string>

Charge les données de jeu à partir de YouTube sous la forme d'une chaîne sérialisée.

Le jeu doit gérer toute analyse entre la chaîne et un format interne.

Exemple

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

Renvoie
`Promise<string>`	Une promesse qui se termine lorsque le chargement a réussi et qui est refusée avec un `ytgame.SdkError` en cas d'échec.

saveData

saveData(data: string): Promise<void>

Enregistre les données de jeu sur YouTube sous la forme d'une chaîne sérialisée.

La chaîne doit être une chaîne UTF-16 valide et bien structurée, d'une taille maximale de 3 Mo. Le jeu doit gérer toute analyse entre la chaîne et un format interne. Si nécessaire, utilisez String.isWellFormed() pour vérifier si la chaîne est bien structurée.

Exemple

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

Paramètres
`data: string`

Renvoie
`Promise<void>`	Une promesse qui se résout lorsque l'enregistrement a réussi et qui est rejetée avec un `ytgame.SdkError` en cas d'échec.

ytgame.health

Fonctions et propriétés liées à la santé du jeu.

Fonctions
`logError`	Enregistre une erreur dans YouTube.
`logWarning`	Enregistre un avertissement sur YouTube.

Fonctions

logError

logError(): void

Enregistre une erreur dans YouTube.

Remarque : Cette API est basée sur le principe du meilleur effort et est limitée en débit, ce qui peut entraîner une perte de données.

Exemple

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

logWarning

logWarning(): void

Enregistre un avertissement dans YouTube.

Remarque : Cette API est basée sur le principe du meilleur effort et est limitée en débit, ce qui peut entraîner une perte de données.

Exemple

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

ytgame.system

Fonctions et propriétés liées au système YouTube

Fonctions
`getLanguage`	Renvoie la langue définie dans les paramètres YouTube de l'utilisateur sous la forme d'une étiquette de langue BCP-47.
`isAudioEnabled`	Indique si l'audio du jeu est activé dans les paramètres YouTube.
`onAudioEnabledChange`	Définit un rappel à déclencher lorsque l'événement de modification des paramètres audio est déclenché depuis YouTube.
`onPause`	Définit un rappel à déclencher lorsqu'un événement de mise en pause du jeu est déclenché depuis YouTube.
`onResume`	Définit un rappel à déclencher lorsqu'un événement de reprise de jeu est déclenché à partir de YouTube.

Fonctions

getLanguage

getLanguage(): Promise<string>

Renvoie la langue définie dans les paramètres YouTube de l'utilisateur sous la forme d'un code de langue BCP-47.

N'utilisez pas d'autres fonctions pour déterminer la langue ou la région de l'utilisateur, ni pour stocker ses préférences linguistiques dans l'enregistrement dans le cloud. Utilisez plutôt cette fonction pour vous assurer que l'expérience utilisateur est cohérente sur YouTube.

Exemple

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

Renvoie
`Promise<string>`	Une promesse qui se termine lorsque l'obtention de la langue a réussi et qui est refusée avec un `ytgame.SdkError` en cas d'échec.

isAudioEnabled

isAudioEnabled(): boolean

Indique si l'audio du jeu est activé dans les paramètres YouTube.

Le jeu DOIT l'utiliser pour initialiser l'état audio du jeu.

Exemple

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

Renvoie
`boolean`	Valeur booléenne indiquant si l'audio est activé.

onAudioEnabledChange

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

Définit un rappel à déclencher lorsque l'événement de modification des paramètres audio est déclenché depuis YouTube.

Le jeu MUST utiliser cette API pour mettre à jour l'état audio du jeu.

Exemple

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

Paramètres
`callback: ((isAudioEnabled: boolean) => void)`	la fonction de rappel à déclencher.

Renvoie
`(() => void)`	une fonction pour définir le rappel qui n'est généralement pas utilisé.

onPause

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

Définit un rappel à déclencher lorsqu'un événement de mise en pause du jeu est déclenché depuis YouTube. Le jeu dispose d'une courte période pour enregistrer un état avant qu'il ne soit supprimé.

onPause est appelé pour tous les types de pauses, y compris lorsque l'utilisateur quitte le jeu. Rien ne garantit que le jeu reprendra.

Exemple

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

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

Paramètres
`callback: (() => void)`	la fonction de rappel à déclencher.

Renvoie
`(() => void)`	une fonction pour définir le rappel qui n'est généralement pas utilisé.

onResume

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

Définit un rappel à déclencher lorsqu'un événement de reprise du jeu est déclenché depuis YouTube.

Après avoir été mis en pause, le jeu ne reprend pas nécessairement.

Exemple

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

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

Paramètres
`callback: (() => void)`	la fonction de rappel à déclencher.

Renvoie
`(() => void)`	une fonction pour définir le rappel qui n'est généralement pas utilisé.

Documentation de référence sur le SDK Jeux intégrés YouTube Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

ytgame

Énumérations

Const SdkErrorType

Variables

Const IN_PLAYABLES_ENV

Const SDK_VERSION

ytgame.SdkError

Propriétés

errorType

ytgame.ads

Fonctions

requestInterstitialAd

ytgame.engagement

Fonctions

openYTContent

sendScore

ytgame.engagement.Content

Propriétés

id

ytgame.engagement.Score

Propriétés

value

ytgame.game

Fonctions

firstFrameReady

gameReady

loadData

saveData

ytgame.health

Fonctions

logError

logWarning

ytgame.system

Fonctions

getLanguage

isAudioEnabled

onAudioEnabledChange

onPause

onResume

Documentation de référence sur le SDK Jeux intégrés YouTube

`Const` SdkErrorType

`Const` IN_PLAYABLES_ENV

`Const` SDK_VERSION