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 à portée globale dans la fenêtre actuelle. Vous NE DEVEZ PAS remplacer cette variable.

Espaces de noms
`ads`	🧪 API EN APERÇU PUBLIC : SUSCEPTIBLE D'ÊTRE MODIFIÉE 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 à l'état du jeu.
`system`	Fonctions et propriétés liées au système YouTube.

Énumérations
`SdkErrorType`	Types d'erreurs générées 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 Jeux intégrés.
`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ées 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 Jeux intégrés. Vous pouvez l'utiliser pour déterminer s'il faut activer ou désactiver les fonctionnalités qui ne sont disponibles que dans les jeux intégrés. Combinez cette vérification avec la vérification 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

Extends 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 EN VERSION PREVIEW PUBLIQUE : SUSCEPTIBLE D'ÊTRE MODIFIÉE SANS PRÉAVIS.

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

Fonctions
`requestInterstitialAd`	Demande l'affichage d'une annonce interstitielle.
`requestRewardedAd`	Demande l'affichage d'une annonce avec récompense pour un type de récompense spécifique.

Fonctions

requestInterstitialAd

requestInterstitialAd(): Promise<void>

Experimental Demande l'affichage d'une annonce interstitielle.

🧪 API en version Preview publique : susceptible d'être modifiée sans préavis.

Ne garantit pas que l'annonce a été diffusée. N'utilisez pas cette API pour récompenser les joueurs qui regardent une annonce.

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 est rejetée/génère une exception en cas de requête infructueuse.

requestRewardedAd

requestRewardedAd(rewardId: string): Promise<boolean>

Experimental Demande l'affichage d'une annonce avec récompense pour un type de récompense spécifique.

🧪 API EN APERÇU PUBLIC : SUSCEPTIBLE D'ÊTRE MODIFIÉE SANS PRÉAVIS.

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

Exemple

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

Paramètres

Paramètres
`rewardId: string`	Obligatoire. Identifiant qui identifie de manière unique le type de récompense pouvant être demandé. Vous devez utiliser un identifiant unique pour chaque type de récompense et réutiliser le même identifiant chaque fois que ce type de récompense spécifique est proposé. Exemple : 21403813-2e22-4316-a8b2-7d4f52a6f6fb : "100 pièces" 7defcfa2-4312-4893-a13a-a84e0c47a4df : "3 vies" 121b001a-0c25-4289-88f6-58e3620d938f : "Passer le niveau"

rewardId: string

Obligatoire. Identifiant qui identifie de manière unique le type de récompense pouvant être demandé. Vous devez utiliser un identifiant unique pour chaque type de récompense et réutiliser le même identifiant chaque fois que ce type de récompense spécifique est proposé. Exemple :

21403813-2e22-4316-a8b2-7d4f52a6f6fb : "100 pièces"
7defcfa2-4312-4893-a13a-a84e0c47a4df : "3 vies"
121b001a-0c25-4289-88f6-58e3620d938f : "Passer le niveau"

Renvoie
`Promise<boolean>`	Promesse qui se résout en cas de requête réussie avec la valeur "true" si l'utilisateur a rempli les conditions pour recevoir une récompense, ou "false" dans le cas contraire. La promesse rejette/génère une exception en cas d'échec de la requête.

ytgame.engagement

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

Interfaces
`Score`	Objet de score que le jeu envoie à YouTube.

Fonctions
`sendScore`	Envoie un score à YouTube.

Fonctions

sendScore

sendScore(score: Score): Promise<void>

Envoie un score à YouTube.

Le score doit représenter une dimension de la progression dans le jeu. S'il existe plusieurs dimensions, le développeur doit en choisir une pour assurer la cohérence. Les scores seront triés et le score le plus élevé sera affiché dans l'UI YouTube. Par conséquent, toute UI de score élevé 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`	la partition à envoyer à YouTube.

Renvoie
`Promise<void>`	Promesse qui se résout en cas de succès et qui est rejetée/génère une exception avec un `ytgame.SdkError` en cas d'échec.

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 sécurisé maximal. Sinon, le score sera refusé.

ytgame.game

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

Fonctions
`firstFrameReady`	Avertit YouTube que le jeu a commencé à afficher des frames.
`gameReady`	Indique à YouTube que le jeu est prêt à être utilisé par les joueurs.
`loadData`	Charge les données de jeu depuis YouTube sous la forme d'une chaîne sérialisée.
`saveData`	Enregistre les données de jeu sur YouTube sous la forme d'une chaîne sérialisée.

Fonctions

firstFrameReady

firstFrameReady(): void

Avertit YouTube que le jeu a commencé à afficher des frames.

Le jeu DOIT appeler cette API. Dans le cas contraire, le jeu ne s'affiche pas pour les utilisateurs. firstFrameReady() DOIT être appelé avant gameReady().

Exemple

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

gameReady

gameReady(): void

Indique à YouTube que le jeu est prêt à être utilisé par les joueurs.

Le jeu DOIT 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 ne passera pas le processus de certification YouTube.

Exemple

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

loadData

loadData(): Promise<string>

Charge les données de jeu depuis 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>`	Promesse qui se termine lorsque le chargement a réussi et qui est rejeté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 formée, et ne doit pas dépasser 3 Mio. 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 formé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>`	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 à l'état du jeu.

Fonctions
`logError`	Consigne une erreur sur YouTube.
`logWarning`	Consigne un avertissement à YouTube.

Fonctions

logError

logError(): void

Enregistre une erreur sur YouTube.

Remarque : Cette API est fournie dans la mesure du possible et son débit est limité, ce qui peut entraîner une perte de données.

Exemple

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

logWarning

logWarning(): void

Enregistre un avertissement sur YouTube.

Remarque : Cette API est fournie en l'état et est soumise à des limites de 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é par 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é depuis YouTube.

Fonctions

getLanguage

getLanguage(): Promise<string>

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

N'utilisez pas d'autres fonctions pour déterminer la langue ou les paramètres régionaux de l'utilisateur, ni pour stocker sa préférence linguistique dans la sauvegarde cloud. Utilisez plutôt cette fonction pour garantir une expérience utilisateur 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>`	Promesse qui se termine lorsque la récupération 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 utiliser cette méthode pour initialiser l'état de l'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é par YouTube.

Le jeu DOIT 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 permettant de désactiver le rappel, qui est généralement inutilisée.

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 fenêtre pour enregistrer tout état avant d'être supprimé.

onPause est appelé pour tous les types de pauses, y compris lorsque l'utilisateur quitte le jeu. Nous ne pouvons pas vous assurer 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 permettant de désactiver le rappel, qui est généralement inutilisée.

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, la reprise du jeu n'est pas garantie.

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 permettant de désactiver le rappel, qui est généralement inutilisée.

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

requestRewardedAd

ytgame.engagement

Fonctions

sendScore

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