Questa pagina è stata tradotta dall'API Cloud Translation.

Annunci con premio

Gli annunci con premio offrono agli utenti la possibilità di interagire con loro in cambio di premi in-app. Questa guida mostra come integrare gli annunci con premio nelle app per Android e iOS utilizzando l'SDK Google Mobile Ads C++.

Leggi alcuni casi di successo dei clienti: case study 1, case study 2.

Prerequisiti

Completa la guida introduttiva.
(Solo Android) Familiarità con i riferimenti a JNI jobject (consulta i suggerimenti di JNI per Android).

Esegui sempre il test con gli annunci di prova

Quando crei e testi le tue app, assicurati di utilizzare gli annunci di prova anziché gli annunci di produzione. In caso contrario, il tuo account potrebbe essere sospeso.

Il modo più semplice per caricare gli annunci di prova è utilizzare l'ID dell'unità pubblicitaria di prova dedicata per gli annunci con premio, che varia a seconda della piattaforma per dispositivo:

Android: ca-app-pub-3940256099942544/5224354917
iOS: ca-app-pub-3940256099942544/1712485313

Sono stati appositamente configurati per restituire annunci di test per ogni richiesta e possono essere utilizzati nelle tue app durante la programmazione, il test e il debug. Assicurati di sostituirla con il tuo ID unità pubblicitaria prima di pubblicare l'app.

Per ulteriori informazioni su come funzionano gli annunci di prova dell'SDK Mobile Ads, consulta Annunci di prova.

Implementazione

Per integrare gli annunci con premio:

Caricare un annuncio.
Registrati per richiamare.
Mostrare l'annuncio e gestire l'evento relativo ai premi.

Configura `RewardedAd`

Gli annunci con premio vengono mostrati negli oggetti RewardedAd, pertanto il primo passo per integrare questi annunci nella tua app consiste nel creare e inizializzare un'istanza di RewardedAd.

Aggiungi la seguente intestazione al codice C++ della tua app:
```
 #include "firebase/gma/rewarded_ad.h"
```

Dichiara e crea un'istanza RewardedAd per un oggetto:

 firebase::gma::RewardedAd* rewarded_ad;
 rewarded_ad = new firebase::gma::RewardedAd();

Inizializza l'istanza RewardedAd utilizzando la trasmissione padre in un tipo AdParent. La vista principale è un riferimento JNI jobject a un Activity Android o un puntatore UIView a iOS.

// my_ad_parent is a jobject reference to an Android Activity or
// a pointer to an iOS UIView.
firebase::gma::AdParent ad_parent =
  static_cast<firebase::gma::AdParent>(my_ad_parent);
firebase::Future<void> result = rewarded_ad->Initialize(ad_parent);

Invece di conservare il futuro come variabile, puoi controllare periodicamente lo stato dell'operazione di inizializzazione richiamando InitializeLastResult() sull'oggetto RewardedAd. Ciò può essere utile per tenere traccia del processo di inizializzazione nel ciclo di gioco globale.

// Monitor the status of the future in your game loop:
firebase::Future<void> result = rewarded_ad->InitializeLastResult();
if (result.status() == firebase::kFutureStatusComplete) {
  // Initialization completed.
  if(future.error() == firebase::gma::kAdErrorCodeNone) {
    // Initialization successful.
  } else {
    // An error has occurred.
  }
} else {
  // Initialization on-going.
}

Per ulteriori informazioni sull'utilizzo di firebase::Future, consulta Utilizzare la funzionalità Future per monitorare lo stato di completamento delle chiamate di metodo.

Carica un annuncio

Il caricamento di un annuncio viene eseguito utilizzando il metodo LoadAd() su un oggetto RewardedAd. Il metodo di caricamento richiede di aver inizializzato l'oggetto RewardedAd e di disporre dell'ID dell'unità pubblicitaria e di un oggetto AdRequest. Viene restituito firebase::Future, che puoi utilizzare per monitorare lo stato e il risultato dell'operazione di caricamento.

Il codice seguente mostra come caricare un annuncio dopo che RewardedAd è stato inizializzato:

firebase::gma::AdRequest ad_request;
firebase::Future<firebase::gma::AdResult> load_ad_result;
load_ad_result = rewarded_ad->LoadAd(rewarded_ad_unit_id, ad_request);

Registrati per i callback

Devi estendere il corso FullScreenContentListener per ricevere le notifiche degli eventi con presentazione di annunci con premio e ciclo di vita. La sottoclasse personalizzata di FullScreenContentListener può essere registrata tramite il metodo RewardedAd::SetFullScreenContentListener() e riceverà richiami quando l'annuncio viene presentato correttamente o meno, nonché quando viene ignorato.

Il codice seguente mostra come estendere la classe e assegnarla all'annuncio:

  class ExampleFullScreenContentListener
      : public firebase::gma::FullScreenContentListener {

   public:
    ExampleFullScreenContentListener() {}

    void OnAdClicked() override {
      // This method is invoked when the user clicks the ad.
    }

    void OnAdDismissedFullScreenContent() override {
     // This method is invoked when the ad dismisses full screen content.
    }

    void OnAdFailedToShowFullScreenContent(const AdError& error) override {
      // This method is invoked when the ad failed to show full screen content.
      // Details about the error are contained within the AdError parameter.
    }

    void OnAdImpression() override {
      // This method is invoked when an impression is recorded for an ad.
    }

    void OnAdShowedFullScreenContent() override {
      // This method is invoked when the ad showed its full screen content.
    }
  };

  ExampleFullScreenContentListener* example_full_screen_content_listener =
    new ExampleFullScreenContentListener();
  rewarded_ad->SetFullScreenContentListener(example_full_screen_content_listener);

RewardedAd è un oggetto utilizzabile una sola volta. Ciò significa che, una volta mostrato, un annuncio con premio non può più essere pubblicato. Una best practice consiste nel caricare un altro annuncio con premio nel metodo OnAdDismissedFullScreenContent() dell'annuncio FullScreenContentListener in modo che il prossimo annuncio con premio inizi a essere caricato non appena quello precedente viene ignorato.

Mostra l'annuncio e gestisci l'evento relativo ai premi

Prima di mostrare un annuncio con premio agli utenti, devi offrire loro la scelta esplicita di visualizzare i contenuti degli annunci con premio in cambio di un premio. Gli annunci con premio devono sempre essere attivati.

Quando presenti il tuo annuncio, devi fornire un oggetto UserEarnedReward per gestire il premio per l'utente.

Il codice che segue mostra come visualizzare RewardedAd:

// A simple listener track UserEarnedReward events.
class ExampleUserEarnedRewardListener :
    public firebase::gma::UserEarnedRewardListener {
 public:
   ExampleUserEarnedRewardListener() { }

  void OnUserEarnedReward(const firebase::gma::AdReward& reward) override {
    // Reward the user!
  }
};

ExampleUserEarnedRewardListener* user_earned_reward_listener =
  new ExampleUserEarnedRewardListener();
firebase::Future<void> result = rewarded_ad->Show(user_earned_reward_listener);

Domande frequenti

Esiste un timeout per la chiamata di inizializzazione?: Dopo 10 secondi, l'SDK C++ di Google Mobile Ads completa il firebase::Future restituito da Initialize() anche se una rete di mediazione non ha ancora completato l'inizializzazione.
Cosa succede se alcune reti di mediazione non sono pronte quando ricevo il callback di inizializzazione?: Una best practice consiste nel caricare gli annunci dopo aver completato l'inizializzazione dell'SDK. Anche se una rete di mediazione non è pronta, l'SDK C++ di Google Mobile Ads chiede comunque un annuncio a questa rete. Pertanto, se una rete di mediazione termina l'inizializzazione dopo il timeout, può comunque gestire le richieste di annunci future in quella sessione.; Puoi continuare a eseguire il polling dello stato di inizializzazione di tutti gli adattatori durante la sessione dell'app chiamando il numero GetInitializationStatus().
Come faccio a scoprire perché una determinata rete di mediazione non è pronta?: AdapterStatus.description() descrive il motivo per cui un adattatore non è pronto per gestire le richieste di annunci. Consulta il codice sorgente della nostra app di esempio con guida rapida in GitHub per un esempio di stato dell'adattatore di mediazione per il logging.

Risorse aggiuntive

Esempio in GitHub

Visualizza il codice sorgente della nostra app di avvio di esempio in GitHub.