Utilizzare l'API Ad Placement

L'API Ad Placement contiene due funzioni: adBreak() e adConfig(), definite nello spazio dei nomi globale seguente. La maggior parte degli argomenti sono funzioni che fornisci per gestire i passaggi chiave della preparazione e della visualizzazione di un annuncio:

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
});

Queste funzioni vengono utilizzate per inserire e configurare gli annunci all'interno del gioco. Gli argomenti mostrati sopra sono gli unici validi che possono essere passati a queste funzioni. Diversi tipi di annunci richiedono diversi sottoinsiemi di questi argomenti, come descritto di seguito.

adBreak() è la funzione chiave per il posizionamento degli annunci all'interno del gioco. Definisce un posizionamento dell'annuncio e accetta un oggetto chiamato configurazione del posizionamento che specifica tutto ciò che è necessario per mostrare un annuncio.

La funzione adBreak() definisce un posizionamento in cui potrebbe essere visualizzato un annuncio. La visualizzazione di un annuncio dipende da fattori quali:

• Il tipo di posizionamento dell'annuncio che hai dichiarato
  • Questo annuncio viene riprodotto all'inizio della partita? Tra i livelli? In un momento in cui il giocatore ha messo in pausa la partita?
• Indica se esiste un annuncio adatto per il player corrente
  • Questo annuncio è pertinente per loro?
  • È coerente con le impostazioni di consenso e privacy dei dati?
• Il numero di annunci visualizzati di recente dal player
• Le impostazioni di controllo, ad esempio la frequenza degli annunci, che hai configurato per questo gioco
  • Come suggerimenti nel tag oppure
  • All'interno di AdSense, tieni presente che i controlli disponibili in AdSense si evolveranno nel tempo.

Anche il tipo di annuncio visualizzato dipende da fattori simili.

Tieni presente che una chiamata a adBreak() potrebbe non mostrare alcun annuncio. Dichiara semplicemente un luogo in cui potrebbe essere mostrato un annuncio.

A differenza delle API tradizionali, in cui il codice sa sempre se un annuncio è disponibile e decidi all'interno del gioco se mostrarlo. Questo approccio di lasciare che l'API Ad Placement decida se un annuncio viene mostrato in un determinato posizionamento è un pattern a volte definito "inversione del controllo".

Il motivo per cui stiamo eseguendo la transizione della nostra API Games a questo modello è innanzitutto che abbrevia il codice che devi scrivere nel gioco. In secondo luogo, semplifica la pubblicazione di posizionamenti conformi alle norme con un'esperienza utente ottimale, il che ci ha permesso di offrire agli editori di giochi alcuni dei nostri formati con il rendimento migliore. Infine, separa in modo più chiaro il processo di inserimento di annunci nel gioco dalle decisioni di monetizzazione relative al tipo e al numero di annunci da mostrare.

Vogliamo che tu possa modificare le impostazioni di monetizzazione e controllare l'esperienza utente senza dover modificare e rilasciare una nuova versione del gioco, inizialmente specificando i suggerimenti nel tag. Tuttavia, nelle versioni future potremo fornire i controlli direttamente nei frontend di AdSense e AdMob.

Annunci interstitial

Un annuncio interstitial è un annuncio a schermo intero che può essere visualizzato in diversi momenti del gioco, ad esempio quando il giocatore inizia a giocare o dopo che ha completato un livello. Mette in pausa il gioco, copre l'intero documento e il giocatore può scegliere di fare clic sull'annuncio (nel qual caso l'annuncio viene visualizzato in un'altra scheda del browser) o di chiuderlo per continuare a giocare.

Nota: un interstitial può essere mostrato prima ancora che il gioco abbia caricato la sua interfaccia utente. Questo tipo di annuncio è chiamato preroll e deve essere trattato in modo leggermente diverso rispetto agli interstitial regolari. Scopri di più sui preroll

Per inserire un annuncio interstitial, compila i seguenti campi nella configurazione del posizionamento:

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'argomento type è obbligatorio e ti consigliamo di assegnare sempre un nome ai tuoi posizionamenti. Gli altri callback sono facoltativi.

Sequenza di chiamate

Esamina la sequenza di chiamate per un annuncio interstitial.

Descrizione

Interstitial - Detailed call sequence
Il tuo gioco H5	API Ad Placement
	Inizializzazione e precaricamento degli annunci
Esecuzione del gioco
Una buona opportunità per mostrare un annuncio… adBreak() →
	È disponibile un annuncio e questo è il momento giusto per mostrarlo… ← beforeAd()
Il gioco viene messo in pausa, l'audio viene disattivato e l'annuncio viene preparato per la visualizzazione. return all'API →
	L'API Ad Placement esegue il rendering dell'annuncio interstitial. Il giocatore può fare clic sull'annuncio (che viene visualizzato in una nuova scheda). Per continuare a giocare, deve chiudere l'annuncio.
	← afterAd() viene chiamato se è stato mostrato un annuncio
Il gioco viene ripreso e l'audio viene riattivato.
	← adBreakDone()adBreakDone() viene sempre chiamato (anche se non è stato mostrato un annuncio)
Il gioco registra le analisi relative a questo posizionamento.

Note

• adBreak() è una funzione asincrona che restituisce immediatamente un valore.
• Se non è presente alcun annuncio da visualizzare per un posizionamento, non viene chiamato alcun callback, ovvero non vengono chiamati beforeAd() e afterAd().
• Per assicurarti che il gioco non continui a essere eseguito durante la visualizzazione dell'annuncio, utilizza il callback beforeAd() per disattivare l'audio e mettere in pausa il gioco.
• beforeAd() è sincrono, l'API Ad Placement non mostrerà un annuncio finché non viene restituito.
• Riavvia la partita e riattiva l'audio quando ricevi la chiamata afterAd().
• Se fornito, adBreakDone() viene sempre chiamato anche se un annuncio non è stato mostrato in questo posizionamento.
• La chiamata di adBreak() mentre viene visualizzato un altro annuncio non andrà a buon fine e nella console JavaScript verrà visualizzato un avviso.

Pre-roll

Un pre-roll è un interstitial che viene visualizzato prima che il gioco carichi la sua UI. È la prima cosa che un giocatore vede quando accede al tuo gioco. Poiché un pre-roll si verifica molto presto nel caricamento della pagina e il gioco non è ancora visualizzato, non sono necessari i soliti richiami per mettere in pausa e disattivare l'audio del gioco. Invece, utilizzi il callback adBreakDone() per sequenziare l'inizio della partita con l'annuncio, ovvero per eseguire il rendering della UI e iniziare a riprodurre il suono. Può essere attivato un solo preroll per ogni caricamento di pagina.

Sequenza di chiamate

La richiesta di un preroll viene effettuata molto presto durante il caricamento della pagina. Poiché a questo punto l'interfaccia utente del gioco non è stata visualizzata, non devi passare i callback beforeAd() e afterAd(). Utilizza invece il callback adBreakDone() per avviare il gioco dopo il posizionamento, in quanto è garantito che venga chiamato anche se non è presente alcun annuncio.

La chiamata del seguente codice, all'inizio della logica di gioco, inserirà un annuncio pre-roll. La UI non deve essere visualizzata prima che venga chiamato questo codice.

// Game must not be running.
// Nothing in the game area should be clickable
adBreak({
   type: ‘preroll',
   adBreakDone: startGame,
})

Pre-rollout - Sequenza di chiamate dettagliata
Il tuo gioco H5	API Ad Placement
	Inizia l'inizializzazione dell'API e la pre-memorizzazione nella cache degli annunci
È in esecuzione, ma non è stato avviato e non ha visualizzato un'interfaccia utente
adBreak(type:'preroll',…) →
	L'API Ad Placement termina l'inizializzazione e il caricamento degli annunci. Se è presente un annuncio, viene mostrato. Il giocatore può fare clic sull'annuncio (che viene visualizzato in una nuova scheda). Per iniziare la partita, deve chiuderlo.
	← adBreakDone() viene sempre chiamato (anche se non è stato mostrato un annuncio)
L'interfaccia utente del gioco viene visualizzata sullo schermo e il giocatore può ora interagire con essa. Il gioco può utilizzare l'oggetto placementInfo passato a adBreakDone() in base alle esigenze (ad esempio, per registrare analisi aggiuntive).

Note

• Un pre-roll tenterà sempre di precaricare gli annunci:
  • La chiamata adConfig(preloadAds: ‘on') non è obbligatoria con i preroll.
• Come altri posizionamenti degli annunci, un pre-roll può mostrare o meno un annuncio.
• beforeAd() e afterAd() non devono essere trasmessi a un preroll.
  • Poiché gli annunci pre-roll vengono pubblicati prima dell'inizio della partita, non è necessario mettere in pausa o disattivare l'audio del gioco.
  • Se trasmetti beforeAd() o afterAd() con un preroll, la chiamata non andrà a buon fine e verrà registrato un errore nella console JavaScript.
• Un preroll attende automaticamente l'inizializzazione dell'API Ad Placement e il precaricamento degli annunci:
  • Tuttavia, è previsto un timeout (2 secondi) che impedisce alla chiamata di ritardare indefinitamente. In questo modo, adBreakDone() viene chiamato in modo tempestivo e il gioco inizia.
  • adBreakDone() viene sempre chiamato anche se non è presente alcun annuncio.
• Ti consigliamo di utilizzare un preroll per inserire gli annunci prima dell'inizio della partita.
  • In alternativa, puoi utilizzare il callback onReady() per adConfig() come meccanismo per sequenziare la logica di gioco con l'inizializzazione dell'API e il precaricamento degli annunci.

Annunci con premio

Un annuncio con premio ti consente di premiare i giocatori con articoli in-app se scelgono di guardare un annuncio. Gli interstitial sono disattivati, un giocatore visualizza l'annuncio e può scegliere di chiuderlo. Gli annunci con premio sono facoltativi. Un giocatore sceglie se e quando guardare un annuncio per ricevere un premio.

A differenza degli annunci interstitial, in cui il giocatore può chiudere l'annuncio in qualsiasi momento, per ricevere una ricompensa deve guardare l'annuncio per un periodo di tempo minimo (che può variare a seconda della creatività dell'annuncio mostrata).

Poiché gli annunci con premio sono facoltativi per il giocatore, richiedono un'integrazione più profonda nel flusso di gioco. Devi fornire funzioni per visualizzare un messaggio di premio all'interno del gioco e per assegnare il premio al giocatore se guarda l'annuncio.

I premi non devono avere valore al di fuori della tua app, non devono avere (o essere facilmente scambiabili con) un valore monetario e non devono essere vendibili o scambiabili con beni e servizi. Inoltre, non devi incoraggiare i giocatori a fare clic sugli annunci. Per ulteriori dettagli, consulta la bozza delle norme relative agli interstitial e ai premi.

Poiché i premi sono facoltativi per il giocatore, puoi aggiungerli ovunque abbia senso all'interno del gioco e puoi utilizzarli in aggiunta agli interstitial. Come gli interstitial, questi posizionamenti sono opportunità per mostrare annunci con premio. L'API Ad Placement chiamerà il tuo codice solo se un annuncio con premio verrà effettivamente offerto in un determinato punto del gioco.

Ancora una volta, l'obiettivo è consentirti di integrare il tuo gioco con l'API Ad Placement una sola volta e poi, nel tempo, utilizzando i controlli nel tag o in AdSense, puoi modificare il mix preciso di annunci attivati, senza dover ricodificare e rilasciare nuovamente il gioco.

Il tipo di un posizionamento con premio è sempre 'reward' e possono essere utilizzati tutti i campi nella configurazione del posizionamento.

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
});

Le nuove funzioni chiave sono beforeReward(), che è il trigger che ti segnala che devi visualizzare il prompt del premio, e adViewed(), che viene chiamata quando il giocatore ha visualizzato correttamente l'annuncio, in modo da poter assegnare il premio.

Potresti definire un posizionamento con premio nel seguente modo:

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

Gli annunci con premio iniziano con un messaggio nel gioco che offre al giocatore un premio se guarda un annuncio.

Sequenza di chiamate per un annuncio con premio

Descrizione

Annuncio con premio: sequenza di chiamate dettagliata
Il tuo gioco H5	API Ad Placement
	Inizializzazione e pre-caching degli annunci
Esecuzione del gioco
adBreak(type:'reward', ... ) →
	È disponibile un annuncio, quindi avvia il posizionamento di un annuncio con premio. beforeReward() viene chiamato in modo sincrono, subito dopo la chiamata a adBreak(). ← beforeReward(showAdFn)
Il gioco esegue il rendering del prompt del premio. In questo modo, il giocatore ha la possibilità di ottenere un premio guardando un annuncio. Potrebbe essere offerto più di un tipo di premio (ad esempio, una nuova vita o una moneta d'oro). Il giocatore può fare clic su un messaggio di premio, ignorarlo o semplicemente ignorarlo. Se fa clic su un prompt, il gioco memorizza il tipo di premio richiesto e chiama showAdFn()... In caso contrario, se il prompt della ricompensa viene chiuso o ignorato, non succederà nulla finché non effettui un'altra chiamata a adBreak() con un tipo di posizionamento della ricompensa. A questo punto, l'API Ad Placement verrà reimpostata e lo stato di questa chiamata verrà pulito. Se l'app chiama showAdFn da un'interruzione pubblicitaria precedente, non ha alcun effetto.
showAdFn() →
	← beforeAd()
Il gioco viene messo in pausa, l'audio viene disattivato e l'annuncio viene preparato per la visualizzazione. return all'API →
	L'API mostra l'annuncio. Ha un pulsante di chiusura e un conto alla rovescia che indica il tempo rimanente dell'annuncio.
SE il player ignora l'annuncio...
	← adDismissed()
Il giocatore ha chiuso l'annuncio e il gioco non ha emesso la ricompensa.
ELSE the player watches the ad to completion...
	← adViewed()
Il giocatore ha guardato l'annuncio fino al completamento e il gioco emette la ricompensa. In genere, ciò avviene impostando uno stato del gioco che viene poi ripristinato al riavvio del gioco con la chiamata a afterAd() riportata di seguito.
Dopo che l'annuncio è stato guardato o chiuso...
	← afterAd() viene chiamato se è stato mostrato un annuncio
Il gioco viene ripreso e l'audio viene riattivato.
	← adBreakDone()adBreakDone() viene sempre chiamato (anche se non è stato mostrato un annuncio)
Il gioco registra le analisi relative a questo posizionamento.

Note

• adBreak() è una funzione asincrona che restituisce immediatamente un valore.
• Se non è presente alcun annuncio da visualizzare per un posizionamento, non viene chiamato nessuno dei callback, ovvero nessuno di beforeAd() e beforeReward().
• Per assicurarti che il gioco non continui a essere eseguito durante la visualizzazione dell'annuncio, utilizza il callback beforeAd() per disattivare l'audio e mettere in pausa il gioco.
• beforeAd() è sincrono, l'API Ad Placement non mostrerà un annuncio finché non viene restituito.
• Riavvia la partita e riattiva l'audio quando ricevi la chiamata afterAd().
• Se fornito, adBreakDone() viene sempre chiamato anche se un annuncio non è stato mostrato in questo posizionamento.
• La chiamata di adBreak() mentre viene visualizzato un altro annuncio non andrà a buon fine e nella console JavaScript verrà visualizzato un avviso.