Integrazione annunci in-game

Ultimo aggiornamento: 2026-08-11

Integra annunci Banner, interstitial e rewarded tramite il bridge host PlayNova. Il gioco gira in un iframe e comunica con l'host via postMessage — non incorporare SDK pubblicitari di terze parti nel pacchetto.

Come funziona la monetizzazione

PlayNova eroga annunci lato host e condivide i ricavi con creatori certificati (70% creatore di default). I giochi richiedono solo show/load; l'host gestisce inventario, limiti di frequenza e reporting impression/click.

Envelope per ogni messaggio:

json

{ "source": "...", "type": "...", "payload": { } }

I giochi devono impostare source su playnova-game
L'host risponde con source playnova-host

Formati annuncio:

Rewarded — opt-in giocatore (revive, doppia ricompensa, oggetto gratis). Concedi ricompense solo dopo ads.rewarded_completed.
Interstitial — pause naturali (livello completato / game over). Mai durante l'input.
Banner — striscia dell'host; il gioco richiede solo show/hide.

Placement consigliati

Passa sempre una stringa placement stabile per analitiche e limiti. Preferisci i nomi piattaforma sotto:

Placement	Caso d'uso
`revive`	Continua dopo fallimento
`double_reward`	Bonus fine livello
`free_item` / `unlock`	Consumabile o sblocco contenuto
`level_complete` / `level_start` / `game_over` / `pause`	Momenti interstitial
`banner_bottom` / `banner_top`	Slot Banner

Flusso di integrazione

In una pausa naturale, chiama ads.load_* con placement (e requestId opzionale).
Attendi ads.*_loaded (o gestisci *_failed e continua senza annunci).
Chiama ads.show_* con lo stesso requestId / placement.
Per rewarded, modifica lo stato del gioco solo su ads.rewarded_completed. Su dismissed/failed, non concedere la ricompensa.

Tipi messaggi bridge

Le stringhe type canoniche sono definite in playnova-web (ads-bridge). Allinea il pacchetto gioco a questi valori esatti.

Gioco → host

type	Scopo
`ads.load_rewarded`	Precarica inventario rewarded
`ads.show_rewarded`	Mostra rewarded (concedi solo dopo completamento)
`ads.load_interstitial`	Precarica interstitial
`ads.show_interstitial`	Mostra interstitial in pausa
`ads.show_banner`	Richiedi Banner host visibile
`ads.hide_banner`	Nascondi Banner host
`ads.preload`	Precarica più formati
`ads.get_banner_height`	Interroga altezza Banner per layout

Host → gioco

type	Scopo
`ads.rewarded_loaded`	Rewarded pronto da mostrare
`ads.rewarded_failed`	Load/show rewarded fallito
`ads.rewarded_completed`	Rewarded completato — sicuro concedere
`ads.rewarded_dismissed`	Rewarded chiuso presto — non concedere
`ads.interstitial_loaded`	Interstitial pronto
`ads.interstitial_failed`	Interstitial fallito
`ads.interstitial_closed`	Interstitial chiuso
`ads.banner_shown`	Banner visibile
`ads.banner_hidden`	Banner nascosto
`ads.banner_failed`	Banner fallito

Helper copia-incolla

Incolla in index.html (o modulo). Sostituisci la concessione ricompensa con la tua logica di gioco.

function pnAds(type, payload) {
  parent.postMessage({ source: 'playnova-game', type, payload }, '*');
}
function onPnHost(handler) {
  window.addEventListener('message', (e) => {
    const d = e.data;
    if (!d || d.source !== 'playnova-host') return;
    handler(d);
  });
}
// Esempio: flusso revive
pnAds('ads.load_rewarded', { placement: 'revive' });
onPnHost((msg) => {
  if (msg.type === 'ads.rewarded_loaded') {
    pnAds('ads.show_rewarded', {
      requestId: msg.payload && msg.payload.requestId,
      placement: 'revive',
      reward: { type: 'life', amount: 1 },
    });
  }
  if (msg.type === 'ads.rewarded_completed') {
    // concedi ricompensa SOLO qui
  }
});

Regole di produzione

Niente auto-click, loop forzati o occultamento controlli Close / Skip.
Non concedere ricompense senza ads.rewarded_completed per quel requestId.
Rispetta errori host: inventario vuoto, continua il gioco normalmente.
Preferisci load prima di show per meno attesa al trigger.
Pacchetti senza SDK annunci terze parti, tracker o script pop-under.
La frequenza interstitial è imposta dall'host; spam show può essere ignorato.

FAQ

Posso usare AdMob / Unity Ads nello zip?

No. PlayNova aggrega la domanda sull'host. Incorporare altri SDK fallisce la review e rompe le ipotesi sandbox iframe.

Cosa succede se l'host non risponde?

Tratta silenzio o *_failed come no-fill. Continua il gameplay senza bloccare il giocatore con spinner infinito.

Dove vedo i ricavi?

Dopo annunci live in produzione, impression e ricavi vanno in analytics creatore. Liquidazione secondo termini del programma.

Il bridge host è live sulla play page. I tipi messaggio sopra sono il contratto production — implementali ora.

Integrazione annunci in-game ​

Come funziona la monetizzazione ​

Placement consigliati ​

Flusso di integrazione ​

Tipi messaggi bridge ​

Gioco → host ​

Host → gioco ​

Helper copia-incolla ​

Regole di produzione ​

FAQ ​

Posso usare AdMob / Unity Ads nello zip? ​

Cosa succede se l'host non risponde? ​

Dove vedo i ricavi? ​