Annunci con premio


Gli annunci con premio offrono agli utenti la possibilità di interagire con gli annunci 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 alcune storie di successo dei clienti: case study 1, case study 2.

Prerequisiti

Esegui sempre i test con gli annunci di prova

Durante la creazione e il test delle tue app, assicurati di utilizzare annunci di prova anziché annunci di prodotto. In caso contrario, il tuo account potrebbe essere sospeso.

Il modo più semplice per caricare annunci di prova è utilizzare il nostro ID unità pubblicitaria di test dedicato per gli annunci con premio, che varia in base alla piattaforma del dispositivo:

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

Sono state configurate appositamente per restituire annunci di prova per ogni richiesta e puoi utilizzarle liberamente nelle tue app durante la programmazione, i test e il debug. Assicurati di sostituirlo con il tuo ID unità pubblicitaria prima di pubblicare l'app.

Per saperne di più sul funzionamento degli annunci di prova dell'SDK per gli annunci per dispositivi mobili, consulta Annunci di prova.

Implementazione

I passaggi principali per integrare gli annunci con premio sono:

  1. Carica un annuncio.
  2. Registrati per i callback.
  3. Visualizza l'annuncio e gestisci l'evento premio.

Configura un RewardedAd

Gli annunci con premio vengono visualizzati negli oggetti RewardedAd, quindi il primo passaggio per integrare gli annunci con premio nella tua app è creare e inizializzare un'istanza di RewardedAd.

  1. Aggiungi la seguente intestazione al codice C++ della tua app: 

     #include "firebase/gma/rewarded_ad.h"

  2. Dichiara e crea un'istanza di un oggetto RewardedAd: 

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

  3. Inizializza l'istanza RewardedAd utilizzando il cast della vista genitore in un tipo AdParent. La vista principale è un riferimento JNI jobject a un Activity Android o un puntatore a un UIView 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);

  4. In alternativa alla conservazione del future come variabile, puoi controllare periodicamente lo stato dell'operazione di inizializzazione richiamando InitializeLastResult() sull'oggetto RewardedAd. Questo può essere utile per tenere traccia del processo di inizializzazione nel loop 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 saperne di più sull'utilizzo di firebase::Future, consulta Utilizza i future per monitorare lo stato di completamento delle chiamate ai metodi.

Carica un annuncio

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

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

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 la classe FullScreenContentListener per ricevere notifiche sulla presentazione degli annunci con premio e sugli eventi del ciclo di vita. La tua sottoclasse FullScreenContentListener personalizzata può essere registrata tramite il metodo RewardedAd::SetFullScreenContentListener() e riceverà callback quando l'annuncio viene presentato correttamente o meno, nonché quando viene ignorato.

Il seguente codice 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 monouso. Ciò significa che, una volta mostrato, un annuncio con premio non può essere mostrato di nuovo. Una best practice consiste nel caricare un altro annuncio con premio nel metodo OnAdDismissedFullScreenContent() di FullScreenContentListener, in modo che il caricamento dell'annuncio con premio successivo inizi non appena viene ignorato quello precedente.

Mostra l'annuncio e gestisci l'evento premio

Prima di mostrare un annuncio con premio agli utenti, devi presentare loro una scelta esplicita per visualizzare i contenuti dell'annuncio con premio in cambio di un premio. Gli annunci con premio devono sempre essere un'esperienza basata sull'attivazione.

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

Il seguente codice mostra come visualizzare un 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 Google Mobile Ads per C++ completa l'oggetto 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?

È consigliabile caricare gli annunci dopo il completamento dell'inizializzazione dell'SDK. Anche se una rete di mediazione non è pronta, l'SDK Google Mobile Ads C++ richiederà comunque un annuncio a quella 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 GetInitializationStatus().

Come faccio a sapere 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 della guida rapida su GitHub per un esempio di registrazione dello stato dell'adattatore di mediazione.

Risorse aggiuntive

Esempio in GitHub