Utiliser l'API Ad Placement

L'API Ad Placement contient deux fonctions : adBreak() et adConfig(), définies dans l'espace de noms global suivant. La plupart des arguments sont des fonctions que vous fournissez et qui vous permettent de gérer les étapes clés de la préparation et de l'affichage d'une annonce :

adBreak({
   type: '<type>',                      // The type of this placement
   name: '<name>',                      // A descriptive name for this placement
   beforeAd: () => {},                  // Prepare for the ad. Mute and pause the game flow
   afterAd: () => {},                   // Resume the game and un-mute the sound
   beforeReward: (showAdFn) => {},      // Show reward prompt (call showAdFn() if clicked)
   adDismissed: () => {},               // Player dismissed the ad before completion
   adViewed: () => {},                  // Ad was viewed and closed
   adBreakDone: (placementInfo) => {},  // Always called (if provided) even if an ad didn't show
});

adConfig({
   preloadAdBreaks: 'on|auto',      // Should ads always be preloaded
   sound: 'on|off',                 // Is sound currently enabled within the game
});

Ces fonctions permettent de placer et de configurer des annonces dans votre jeu. Les arguments présentés ci-dessus sont les seuls arguments valides qui peuvent être transmis à ces fonctions. Différents types d'annonces nécessitent différents sous-ensembles de ces arguments, comme indiqué ci-dessous.

adBreak() est la fonction clé pour placer des annonces dans votre jeu. Il définit un emplacement publicitaire et accepte un objet appelé configuration de l'emplacement qui spécifie tout ce qui est nécessaire pour diffuser une annonce.

La fonction adBreak() définit un emplacement où une annonce pourrait être diffusée. L'affichage d'une annonce dépend de facteurs tels que :

  • Type d'emplacement d'annonce que vous avez déclaré
    • Cette annonce est-elle diffusée au début du jeu ? Entre les niveaux ? À un moment où le joueur a mis le jeu en pause ?
  • Indique si une annonce appropriée existe pour le lecteur actuel.
    • Cette annonce est-elle pertinente pour eux ?
    • Est-ce que cela correspond à leurs paramètres de confidentialité et de consentement des données ?
  • Nombre d'annonces que le joueur a vues récemment
  • Les paramètres de contrôle que vous avez configurés pour ce jeu (par exemple, la fréquence des annonces)
    • soit sous forme d'indications dans la balise ;
    • Dans AdSense (notez que les commandes disponibles dans AdSense évolueront au fil du temps).

Le type d'annonce diffusée dépend également de facteurs similaires.

Notez qu'un appel à adBreak() peut ne pas afficher d'annonce du tout. Il déclare simplement un emplacement où une annonce pourrait être diffusée.

Cela diffère des API traditionnelles dans lesquelles votre code sait toujours si une annonce est disponible et vous décidez dans le jeu s'il faut l'afficher. Cette approche, qui consiste à laisser l'API Ad Placement décider si une annonce doit être diffusée dans un emplacement spécifique, est un modèle parfois appelé "inversion de contrôle".

La raison pour laquelle nous faisons passer notre API Games à ce modèle est, tout d'abord, qu'il raccourcit le code que vous devez écrire dans votre jeu. Deuxièmement, cela nous permet de proposer plus facilement des emplacements conformes aux règles et offrant une expérience utilisateur de qualité. Nous avons ainsi pu proposer certains de nos formats les plus performants aux éditeurs de jeux. Enfin, il sépare plus clairement le processus de placement des annonces dans votre jeu des décisions de monétisation concernant le type et le nombre d'annonces à afficher.

Nous souhaitons que vous puissiez modifier vos paramètres de monétisation et contrôler l'expérience utilisateur sans avoir à modifier et à publier une nouvelle version de votre jeu, en spécifiant d'abord des indices dans la balise. Toutefois, dans les prochaines versions, nous pourrons fournir des contrôles directement dans les interfaces AdSense et AdMob.

Annonces interstitielles

Une annonce interstitielle est une annonce en plein écran qui peut s'afficher à différents moments de votre jeu, par exemple lorsque le joueur le lance ou lorsqu'il termine un niveau. Le jeu est mis en pause et l'annonce recouvre l'intégralité du document. Le joueur peut choisir de cliquer sur l'annonce (qui s'affiche alors dans un autre onglet de son navigateur) ou de la fermer pour continuer à jouer.

Pour diffuser une annonce interstitielle, renseignez les champs suivants dans la configuration de l'emplacement :

adBreak({
   type: 'start',           // The type of this placement
   name: 'game_started',    // A descriptive name for this placement
   beforeAd: beforeAd,      // Prepare for the ad. Mute and pause the game flow
   afterAd: afterAd,        // Resume the game and un-mute the sound
   adBreakDone: breakDone,  // Always called (if provided) even if an ad didn't show
});

L'argument type est obligatoire. Nous vous recommandons de toujours nommer vos emplacements. Les autres rappels sont facultatifs.

Séquence d'appel

Examinez la séquence d'appel pour une annonce interstitielle.

Diagramme de séquence d&#39;appel d&#39;annonce interstitielle

Description

Interstitiel : séquence d'appel détaillée
Votre jeu H5 Ad Placement API
  Initialisation et préchargement des annonces
Exécuter le jeu  

Une bonne opportunité de diffuser une annonce…

adBreak() →

 
 

Une annonce est disponible et le moment est bien choisi pour la diffuser…

← beforeAd()
Le jeu se met en pause, coupe le son et se prépare à afficher l'annonce.

return à l'API →

 
  L'API Ad Placement affiche l'annonce interstitielle. Le joueur peut cliquer sur l'annonce (qui s'affiche dans un nouvel onglet). Il doit fermer l'annonce pour continuer à jouer.
  ← afterAd() est appelé si une annonce a été diffusée.
Le jeu est mis en pause et le son est réactivé.  
  ← adBreakDone()adBreakDone() est toujours appelé (même si aucune annonce n'a été diffusée)
Le jeu enregistre des données analytiques sur cet emplacement.  

Remarques

  • adBreak() est une fonction asynchrone qui renvoie immédiatement un résultat.
  • Si aucune annonce ne peut être diffusée pour un emplacement, aucun des rappels n'est appelé (c'est-à-dire que ni beforeAd() ni afterAd() ne sont appelés).
  • Pour vous assurer que votre jeu ne continue pas à s'exécuter pendant l'affichage de l'annonce, utilisez le rappel beforeAd() pour couper le son et mettre le jeu en pause.
  • beforeAd() étant synchrone, l'API Ad Placement n'affichera pas d'annonce tant qu'elle n'aura pas renvoyé de réponse.
  • Redémarrez votre jeu et réactivez le son lorsque vous recevez l'appel afterAd().
  • Si elle est fournie, adBreakDone() est toujours appelée, même si aucune annonce n'a été diffusée dans cet emplacement.
  • L'appel de adBreak() pendant l'affichage d'une autre annonce échouera et un avertissement s'affichera dans la console JavaScript.

Annonces vidéo pré-roll

Un préroll est un interstitiel qui s'affiche avant que votre jeu ne charge son UI. C'est la première chose qu'un joueur voit lorsqu'il accède à votre jeu. Étant donné qu'un préroll se produit très tôt dans le chargement de la page et que votre jeu n'est pas encore affiché, les appels habituels pour mettre en pause et couper le son de votre jeu ne sont pas nécessaires. Vous utilisez plutôt le rappel adBreakDone() pour séquencer le début de votre jeu avec l'annonce, c'est-à-dire pour afficher l'UI et lancer la lecture du son. Un seul préroll peut être déclenché pour chaque chargement de page.

Séquence d'appel

L'appel à un préroll est effectué très tôt dans le chargement de la page. Comme votre jeu n'a pas encore affiché son UI à ce stade, vous ne devez pas transmettre les rappels beforeAd() et afterAd(). Utilisez plutôt le rappel adBreakDone() pour démarrer votre jeu après l'emplacement, car il est garanti d'être appelé même s'il n'y avait pas d'annonce.

Diagramme de séquence d&#39;appel d&#39;annonce pré-roll

L'appel du code suivant, tôt dans la logique de votre jeu, placera un préroll. Votre UI ne doit pas être affichée avant l'appel de ce code.

// Game must not be running.
// Nothing in the game area should be clickable
adBreak({
   type: ‘preroll',
   adBreakDone: startGame,
})
Séquence d'appel détaillée pour le préroll
Votre jeu H5 Ad Placement API
  L'initialisation de l'API et la mise en cache préalable des annonces commencent.
En cours d'exécution, mais n'a pas démarré et n'a pas affiché d'UI  

adBreak(type:'preroll',…) →

 
 

L'API Ad Placement termine l'initialisation et le chargement des annonces. Si une annonce est disponible, elle est diffusée. Le joueur peut cliquer sur l'annonce (qui s'affiche dans un nouvel onglet). Il doit le fermer pour que le jeu puisse démarrer.

 

← adBreakDone() est toujours appelé (même si aucune annonce n'a été diffusée)

L'UI du jeu est affichée à l'écran et le joueur peut maintenant interagir avec. Le jeu peut utiliser l'objet placementInfo transmis à adBreakDone() selon les besoins (par exemple, pour enregistrer des données analytiques supplémentaires).

  

Remarques

  • Un préroll tente toujours de précharger les annonces :
    • L'appel de adConfig(preloadAds: ‘on') n'est pas nécessaire avec les prérolls.
  • Comme les autres emplacements publicitaires, un pré-roll peut ou non diffuser une annonce.
  • beforeAd() et afterAd() ne doivent pas être transmis à un préroll.
    • Étant donné que les annonces pré-roll sont diffusées avant le début de votre jeu, il n'est pas nécessaire de mettre le jeu en pause ni de couper le son.
    • Si vous transmettez beforeAd() ou afterAd() avec un préroll, l'appel échouera et une erreur sera consignée dans la console JavaScript.
  • Un préroll attend automatiquement que l'API Ad Placement s'initialise et précharge les annonces :
    • Toutefois, un délai d'attente (2 s) empêche l'appel d'être retardé indéfiniment. Cela garantit que adBreakDone() est appelé en temps voulu et que votre jeu démarre.
    • adBreakDone() est toujours appelé, même en l'absence d'annonce.
  • Nous vous recommandons d'utiliser un préroll pour diffuser des annonces avant le début de votre jeu.
    • Vous pouvez également utiliser le rappel onReady() pour adConfig() comme mécanisme de séquençage de la logique de votre jeu avec l'initialisation de l'API et le préchargement des annonces.

Annonces avec récompense

Une annonce avec récompense vous permet de récompenser vos joueurs avec des éléments intégrés s'ils choisissent de regarder une annonce. Contrairement aux interstitiels, qui sont désactivables, les annonces avec lecteur sont affichées aux joueurs, qui peuvent choisir de les fermer. Les annonces avec récompense sont facultatives. Un joueur choisit s'il souhaite regarder une annonce et quand il souhaite le faire pour recevoir une récompense.

Contrairement aux annonces interstitielles, que le joueur peut fermer à tout moment, il doit regarder les annonces avec récompense pendant une durée minimale (qui peut varier en fonction de la création publicitaire diffusée) pour recevoir une récompense.

Comme les annonces avec récompense sont facultatives pour le joueur, elles nécessitent une intégration plus poussée dans le déroulement de votre jeu. Vous devez fournir des fonctions pour afficher une invite de récompense dans votre jeu et pour attribuer la récompense au joueur s'il regarde l'annonce.

Les récompenses ne doivent pas avoir de valeur en dehors de votre application. Elles ne doivent pas avoir de valeur monétaire (ni être facilement échangeables contre de l'argent), ni être vendues ou échangeables contre des biens et services. Vous ne devez pas non plus encourager les joueurs à cliquer sur les annonces. Pour en savoir plus, veuillez consulter le projet de règlement sur les interstitiels et les annonces avec récompense.

Étant donné que les récompenses sont facultatives pour le joueur, vous pouvez les ajouter où bon vous semble dans votre jeu et les utiliser en plus des annonces interstitielles. Comme les interstitiels, ces emplacements sont des opportunités de diffuser des annonces avec récompense. L'API Ad Placement n'appellera votre code que si une annonce avec récompense doit être proposée à un moment donné de votre jeu.

L'objectif est de vous permettre d'intégrer votre jeu à l'API AdPlacement une seule fois. Ensuite, au fil du temps, vous pourrez modifier la combinaison précise d'annonces activées à l'aide de commandes dans la balise ou dans AdSense, sans avoir à recoder ni à republier votre jeu.

Le type d'emplacement avec récompense est toujours 'reward'. Tous les champs de la configuration de l'emplacement peuvent être utilisés.

adBreak({
   type: 'reward',                      // The type of this placement
   name: '<name>',                      // A descriptive name for this placement
   beforeAd: () => {},                  // Prepare for the ad. Mute and pause the game flow
   afterAd: () => {},                   // Resume the game and re-enable sound
   beforeReward: (showAdFn) => {},      // Show reward prompt (call showAdFn() if clicked)
   adDismissed: () => {},               // Player dismissed the ad before it finished.
   adViewed: () => {},                  // Player watched the ad–give them the reward.
   adBreakDone: (placementInfo) => {},  // Always called (if provided) even if an ad didn't show
});

Les nouvelles fonctions clés sont beforeReward(), qui est le déclencheur qui indique que vous devez afficher l'invite de récompense, et adViewed(), qui est appelée lorsque le joueur a regardé l'annonce, ce qui vous permet de lui attribuer sa récompense.

Vous pouvez définir un emplacement avec récompense comme suit :

adBreak({
   type: 'reward',
   name: 'new_life_reward_1',
   beforeAd: pauseGame,
   afterAd: restartGame,
   beforeReward: showRewardPrompt,
   adDismissed: adDismissed,
   adViewed: adViewed,
   adBreakDone: breakDone,
});

Les annonces avec récompense commencent par une invite dans votre jeu qui propose au joueur une récompense s'il regarde une annonce.

Exemple de requête publicitaire : Regardez une vidéo pour obtenir une vie supplémentaire

Séquence d'appel pour une annonce avec récompense

Diagramme de séquence d&#39;appel avec récompense

Description

Annonce avec récompense : séquence d'appels détaillée
Votre jeu H5 Ad Placement API
  Initialisation et pré-mise en cache des annonces
Exécuter le jeu  

adBreak(type:'reward', ... ) →

 
 

Une annonce est disponible. Commencez donc à diffuser une annonce avec récompense. beforeReward() est appelé de manière synchrone, immédiatement après l'appel de adBreak().

← beforeReward(showAdFn)

Le jeu affiche l'invite de récompense. Cela permet au joueur d'obtenir une récompense en regardant une annonce. Plusieurs types de récompenses peuvent être proposés (par exemple, une nouvelle vie ou une pièce d'or).

Le joueur peut cliquer sur une invite de récompense, la fermer ou simplement l'ignorer.

S'il clique sur une invite, le jeu stocke le type de récompense demandé et appelle showAdFn()....

Sinon, si l'invite de récompense est fermée ou ignorée, rien ne se passe jusqu'à ce que vous effectuiez un autre appel à adBreak() avec un type d'emplacement de récompense. À ce moment-là, l'API Ad Placement réinitialise et nettoie l'état de cet appel. Si l'application appelle showAdFn à partir d'un précédent emplacement publicitaire, cela n'a aucun effet.

  

showAdFn() →

 
  ← beforeAd()

Le jeu se met en pause, coupe le son et se prépare à afficher l'annonce.

return à l'API →

 
  L'API affiche l'annonce. Il comporte un bouton de fermeture et un compte à rebours indiquant le temps restant de l'annonce.
SI le lecteur ignore l'annonce…
  ← adDismissed()
Le joueur a fermé l'annonce, mais le jeu ne lui a pas accordé la récompense.  
SINON, le joueur regarde l'annonce jusqu'à la fin…
  ← adViewed()
Le joueur a regardé l'annonce en entier et le jeu lui a attribué la récompense. (Cela se fait généralement en définissant un état de jeu qui est ensuite récupéré lorsque le jeu redémarre avec l'appel à afterAd() ci-dessous.)  
Après avoir regardé ou ignoré l'annonce…
  ← afterAd() est appelé si une annonce a été diffusée.
Le jeu est mis en pause et le son est réactivé.  
  ← adBreakDone()adBreakDone() est toujours appelé (même si aucune annonce n'a été diffusée)
Le jeu enregistre des données analytiques sur cet emplacement.  

Remarques

  • adBreak() est une fonction asynchrone qui renvoie immédiatement un résultat.
  • Si aucune annonce n'est disponible pour un emplacement, aucun rappel n'est appelé (c'est-à-dire que ni beforeAd() ni beforeReward() ne sont appelés).
  • Pour vous assurer que votre jeu ne continue pas à s'exécuter pendant l'affichage de l'annonce, utilisez le rappel beforeAd() pour couper le son et mettre le jeu en pause.
  • beforeAd() étant synchrone, l'API Ad Placement n'affichera pas d'annonce tant qu'elle n'aura pas renvoyé de réponse.
  • Redémarrez votre jeu et réactivez le son lorsque vous recevez l'appel afterAd().
  • Si elle est fournie, adBreakDone() est toujours appelée, même si aucune annonce n'a été diffusée dans cet emplacement.
  • L'appel de adBreak() pendant l'affichage d'une autre annonce échouera et un avertissement s'affichera dans la console JavaScript.