Annunci con premio

Gli annunci con premio sono annunci con cui gli utenti possono interagire in cambio di premi in-app. Questa guida illustra come integrare gli annunci con premio di AdMob in un'app per iOS. Leggi alcuni casi di successo dei clienti: case study 1, case study 2.

Prerequisiti

• SDK Google Mobile Ads 8.0.0 o versioni successive.
• Completa la Guida introduttiva.

Effettua sempre test con annunci di prova

Quando crei e testi le tue app, assicurati di utilizzare annunci di prova anziché annunci di produzione pubblicati. In caso contrario, l'account verrà sospeso.

Il modo più semplice per caricare gli annunci di prova è utilizzare il nostro ID unità pubblicitaria di prova dedicato per gli annunci con premio per iOS:

ca-app-pub-3940256099942544/1712485313

È stato appositamente configurato per restituire annunci di prova per ogni richiesta e puoi utilizzarlo 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 ulteriori informazioni sul funzionamento degli annunci di prova dell'SDK Mobile Ads, consulta la pagina Annunci di prova.

Implementazione

Suggerimento: per implementare gli annunci con premio utilizzando SwiftUI, consulta la sezione Annunci a schermo intero.

Di seguito sono riportati i passaggi principali per integrare gli annunci con premio:

• Carica un annuncio
• [Facoltativo] Convalida i callback SSV
• Registrati per le richiamate
• Visualizzare l'annuncio e gestire l'evento di ricompensa

Carica un annuncio

Il caricamento di un annuncio viene eseguito utilizzando il metodo loadWithAdUnitID:request:completionHandler: statico nella classe GADRewardedAd. Il metodo di caricamento richiede l'ID unità pubblicitaria, un oggetto GADRequest e un gestore del completamento che viene chiamato quando il caricamento dell'annuncio va a buon fine o meno. L'oggetto GADRewardedAd caricato viene fornito come parametro nel gestore di completamento. L'esempio seguente mostra come caricare un GADRewardedAd nel tuo corso ViewController.

Swift

import GoogleMobileAds
import UIKit

class ViewController: UIViewController {

  private var rewardedAd: GADRewardedAd?

  func loadRewardedAd() {
    do {
      rewardedAd = try await GADRewardedAd.load(
        withAdUnitID: "ca-app-pub-3940256099942544/1712485313", request: GADRequest())
    } catch {
      print("Rewarded ad failed to load with error: \(error.localizedDescription)")
    }
  }
}

Objective-C

@import GoogleMobileAds;
@import UIKit;

@interface ViewController ()

@property(nonatomic, strong) GADRewardedAd *rewardedAd;

@end

@implementation ViewController
- (void)loadRewardedAd {
  GADRequest *request = [GADRequest request];
  [GADRewardedAd
      loadWithAdUnitID:@"ca-app-pub-3940256099942544/1712485313"
                request:request
      completionHandler:^(GADRewardedAd *ad, NSError *error) {
        if (error) {
          NSLog(@"Rewarded ad failed to load with error: %@", [error localizedDescription]);
          return;
        }
        self.rewardedAd = ad;
        NSLog(@"Rewarded ad loaded.");
      }];
}

Suggerimento: puoi utilizzare le chiamate al carico degli annunci per creare una cache degli annunci precaricati prima che tu voglia mostrarli, in modo che gli annunci possano essere mostrati senza latenza quando necessario. Poiché gli annunci scadono dopo un'ora, devi svuotare la cache e ricaricare con nuovi annunci ogni ora.

[Facoltativo] Convalida i callback di verifica lato server (SSV)

Le app che richiedono dati aggiuntivi nei callback della verifica lato server devono utilizzare la funzionalità dei dati personalizzati degli annunci con premio. Qualsiasi valore di stringa impostato in un oggetto annuncio con premio viene trasmesso al parametro di query custom_data del callback SSV. Se non viene impostato un valore dei dati personalizzati, il valore del parametro di query custom_data non sarà presente nel callback SSV.

Il seguente esempio di codice mostra come impostare dati personalizzati su un oggetto annuncio con premio prima di richiedere un annuncio.

Swift

do {
  rewardedAd = try await GADRewardedAd.load(
    withAdUnitID: "ca-app-pub-3940256099942544/1712485313", request: GADRequest())
  let options = GADServerSideVerificationOptions()
  options.customRewardString = "SAMPLE_CUSTOM_DATA_STRING"
  rewardedAd.serverSideVerificationOptions = options
} catch {
  print("Rewarded ad failed to load with error: \(error.localizedDescription)")
}

Objective-C

[GADRewardedAd
     loadWithAdUnitID:@"ca-app-pub-3940256099942544/1712485313"
              request:[GADRequest request];
    completionHandler:^(GADRewardedAd *ad, NSError *error) {
      if (error) {
        // Handle Error
        return;
      }
      self.rewardedAd = ad;
      GADServerSideVerificationOptions *options =
          [[GADServerSideVerificationOptions alloc] init];
      options.customRewardString = @"SAMPLE_CUSTOM_DATA_STRING";
      ad.serverSideVerificationOptions = options;
    }];

Importante: a partire dalla versione 7.50.0 dell'SDK, puoi impostare la stringa premio personalizzata in qualsiasi momento.

Punto chiave: la stringa del premio personalizzata contiene un codice con escape e potrebbe richiedere la decodifica quando analizzata dal callback SSV.

Registrati per le richiamate

Per ricevere notifiche per gli eventi di presentazione, devi implementare il protocollo GADFullScreenContentDelegate e assegnarlo alla proprietà fullScreenContentDelegate dell'annuncio restituito. Il protocollo GADFullScreenContentDelegate gestisce i callback per quando l'annuncio viene presentato correttamente o meno e quando viene ignorato. Il seguente codice mostra come implementare il protocollo e assegnarlo all'annuncio:

Swift

import GoogleMobileAds
import UIKit

class ViewController: UIViewController, GADFullScreenContentDelegate {

  private var rewardedAd: GADRewardedAd?

  func loadRewardedAd() {
    do {
      rewardedAd = try await GADRewardedAd.load(
        withAdUnitID: "ca-app-pub-3940256099942544/1712485313", request: GADRequest())
      rewardedAd?.fullScreenContentDelegate = self
    } catch {
      print("Rewarded ad failed to load with error: \(error.localizedDescription)")
    }
  }

  /// Tells the delegate that the ad failed to present full screen content.
  func ad(_ ad: GADFullScreenPresentingAd, didFailToPresentFullScreenContentWithError error: Error) {
    print("Ad did fail to present full screen content.")
  }

  /// Tells the delegate that the ad will present full screen content.
  func adWillPresentFullScreenContent(_ ad: GADFullScreenPresentingAd) {
    print("Ad will present full screen content.")
  }

  /// Tells the delegate that the ad dismissed full screen content.
  func adDidDismissFullScreenContent(_ ad: GADFullScreenPresentingAd) {
    print("Ad did dismiss full screen content.")
  }
}

Objective-C

@interface ViewController () <GADFullScreenContentDelegate>

@property(nonatomic, strong) GADRewardedAd *rewardedAd;

@end

@implementation ViewController
- (void)loadRewardedAd {
  GADRequest *request = [GADRequest request];
  [GADRewardedAd
      loadWithAdUnitID:@"ca-app-pub-3940256099942544/4806952744"
                request:request
      completionHandler:^(GADRewardedAd *ad, NSError *error) {
        if (error) {
          NSLog(@"Rewarded ad failed to load with error: %@", [error localizedDescription]);
          return;
        }
        self.rewardedAd = ad;
        NSLog(@"Rewarded ad loaded.");
        self.rewardedAd.fullScreenContentDelegate = self;
      }];
}

/// Tells the delegate that the ad failed to present full screen content.
- (void)ad:(nonnull id<GADFullScreenPresentingAd>)ad
    didFailToPresentFullScreenContentWithError:(nonnull NSError *)error {
    NSLog(@"Ad did fail to present full screen content.");
}

/// Tells the delegate that the ad will present full screen content.
- (void)adWillPresentFullScreenContent:(nonnull id<GADFullScreenPresentingAd>)ad {
    NSLog(@"Ad will present full screen content.");
}

/// Tells the delegate that the ad dismissed full screen content.
- (void)adDidDismissFullScreenContent:(nonnull id<GADFullScreenPresentingAd>)ad {
    NSLog(@"Ad did dismiss full screen content.");
}

GADRewardedAd è un oggetto monouso. Ciò significa che un annuncio con premio non può essere mostrato di nuovo. Una best practice consiste nel caricare un altro annuncio con premio nel metodo adDidDismissFullScreenContent: su GADFullScreenContentDelegate in modo che l'annuncio con premio successivo inizi a caricarsi non appena quello precedente viene ignorato.

Visualizzare l'annuncio e gestire l'evento di ricompensa

Prima di mostrare un annuncio con premio agli utenti, devi offrire loro una 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 GADUserDidEarnRewardHandler per gestire il premio per l'utente.

Il seguente codice presenta il metodo migliore per visualizzare un annuncio con premio.

Swift

func show() {
  guard let rewardedAd = rewardedAd else {
    return print("Ad wasn't ready.")
  }

  // The UIViewController parameter is an optional.
  ad.present(fromRootViewController: nil) {
    let reward = ad.adReward
    print("Reward received with currency \(reward.amount), amount \(reward.amount.doubleValue)")
    // TODO: Reward the user.
  }
}

Objective-C

- (void)show {
  if (self.rewardedAd) {
    // The UIViewController parameter is nullable.
    [self.rewardedAd presentFromRootViewController:nil
                                  userDidEarnRewardHandler:^{
                                  GADAdReward *reward =
                                      self.rewardedAd.adReward;
                                  // TODO: Reward the user!
                                }];
  } else {
    NSLog(@"Ad wasn't ready");
  }
}

Domande frequenti

Posso avere i dettagli del premio per GADRewardedAd?

Sì, se hai bisogno dell'importo del premio prima che venga attivato il callback userDidEarnReward, GADRewardedAd ha una proprietà adReward che puoi controllare per verificare l'importo del premio dopo il caricamento dell'annuncio.

C'è un timeout per la chiamata di inizializzazione?

Dopo 10 secondi, l'SDK Google Mobile Ads richiama il GADInitializationCompletionHandler fornito al metodo startWithCompletionHandler:, 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?

Consigliamo di caricare un annuncio all'interno di GADInitializationCompletionHandler. Anche se una rete di mediazione non è pronta, l'SDK Google Mobile Ads chiede 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 GADMobileAds.initializationStatus.

Come faccio a sapere perché una determinata rete di mediazione non è pronta?

La proprietà description di un oggetto GADAdapterStatus descrive perché un adattatore non è pronto per gestire le richieste di annunci.

Il gestore del completamento di userDidEarnRewardHandler viene sempre chiamato prima del metodo delegato adDidDismissFullScreenContent:?

Per Google Ads, tutte le chiamate userDidEarnRewardHandler avvengono prima del giorno adDidDismissFullScreenContent:. Per gli annunci pubblicati tramite la mediazione, l'implementazione dell'SDK della rete pubblicitaria di terze parti determina l'ordine di callback. Per gli SDK delle reti pubblicitarie che forniscono un singolo metodo di delega con informazioni sui premi, l'adattatore di mediazione richiama userDidEarnRewardHandler prima del giorno adDidDismissFullScreenContent:.

Esempi su GitHub

• Esempio di annunci con premio: Swift | Objective-C

Passaggi successivi

Scopri di più sulla privacy dell'utente.