Annunci con premio

Gli annunci con premio sono annunci con cui gli utenti hanno la possibilità di interagire in cambio di premi in-app. Questa guida mostra come integrare gli annunci con premio di AdMob in un'app Unity.

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

Questa guida spiega come integrare gli annunci con premio in un'app Unity.

Prerequisiti

• Completa la Guida introduttiva.

Esegui sempre test con annunci di prova

Il codice di esempio riportato di seguito contiene un ID unità pubblicitaria che puoi utilizzare per richiedere annunci di prova. È stato appositamente configurato per restituire annunci di prova anziché annunci di produzione per ogni richiesta, il che ne rende sicuro l'uso.

Tuttavia, dopo aver registrato un'app nell'AdMob interfaccia web e creato i tuoi ID unità pubblicitaria da utilizzare nell'app, configura esplicitamente il dispositivo come dispositivo di prova durante lo sviluppo.

Android

ca-app-pub-3940256099942544/5224354917

iOS

ca-app-pub-3940256099942544/1712485313

Inizializzare l'SDK Google Mobile Ads

Prima di caricare gli annunci, fai in modo che la tua app inizializza l'SDK Mobile Ads chiamando MobileAds.Initialize(). Questa operazione deve essere eseguita una sola volta, idealmente al momento del lancio dell'app.

using GoogleMobileAds;
using GoogleMobileAds.Api;

public class GoogleMobileAdsDemoScript : MonoBehaviour
{
    public void Start()
    {
        // Initialize the Google Mobile Ads SDK.
        MobileAds.Initialize((InitializationStatus initStatus) =>
        {
            // This callback is called once the MobileAds SDK is initialized.
        });
    }
}

Se utilizzi la mediazione, attendi che venga eseguito il callback prima di caricare gli annunci per assicurarti che tutti gli adattatori di mediazione vengano inizializzati.

Implementazione

Ecco i passaggi principali per integrare gli annunci con premio:

1. Carica l'annuncio con premio
2. [Facoltativo] Convalidare i callback di verifica lato server (SSV)
3. Mostrare l'annuncio con premio quando viene richiamato il premio
4. Ascoltare gli eventi relativi agli annunci con premio
5. Libera spazio nell'annuncio con premio
6. Precarica il successivo annuncio con premio

Carica l'annuncio con premio

Il caricamento di un annuncio con premio viene eseguito utilizzando il metodo Load() statico nella classe RewardedAd. L'oggetto RewardedAd caricato viene fornito come parametro nel gestore di completamento. L'esempio seguente mostra come caricare un elemento RewardedAd.

  // These ad units are configured to always serve test ads.
#if UNITY_ANDROID
  private string _adUnitId = "ca-app-pub-3940256099942544/5224354917";
#elif UNITY_IPHONE
  private string _adUnitId = "ca-app-pub-3940256099942544/1712485313";
#else
  private string _adUnitId = "unused";
#endif

  private RewardedAd _rewardedAd;

  /// <summary>
  /// Loads the rewarded ad.
  /// </summary>
  public void LoadRewardedAd()
  {
      // Clean up the old ad before loading a new one.
      if (_rewardedAd != null)
      {
            _rewardedAd.Destroy();
            _rewardedAd = null;
      }

      Debug.Log("Loading the rewarded ad.");

      // create our request used to load the ad.
      var adRequest = new AdRequest();

      // send the request to load the ad.
      RewardedAd.Load(_adUnitId, adRequest,
          (RewardedAd ad, LoadAdError error) =>
          {
              // if error is not null, the load request failed.
              if (error != null || ad == null)
              {
                  Debug.LogError("Rewarded ad failed to load an ad " +
                                 "with error : " + error);
                  return;
              }

              Debug.Log("Rewarded ad loaded with response : "
                        + ad.GetResponseInfo());

              _rewardedAd = ad;
          });
  }

Avviso: si sconsiglia di caricare un nuovo annuncio dal blocco di completamento delle richieste di annuncio quando il caricamento di un annuncio non è riuscito. Se devi caricare un annuncio dal blocco di completamento delle richieste di annunci, limita i tentativi di caricamento degli annunci per evitare richieste di annuncio continue non riuscite in situazioni quali una connettività di rete limitata.

Suggerimento: puoi utilizzare le chiamate al carico degli annunci per creare una cache di annunci precaricati prima di volerli mostrare, in modo che gli annunci possano essere mostrati con latenza zero quando necessario. Poiché gli annunci scadono dopo un'ora, è consigliabile svuotare la cache e ricaricare gli annunci ogni ora.

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

Le app che richiedono dati aggiuntivi nei callback di verifica lato server devono utilizzare la funzionalità dei dati personalizzati degli annunci con premio. Qualsiasi valore di stringa impostato su un oggetto annuncio con premio viene trasmesso al parametro di query custom_data del callback SSV. Se non è impostato alcun 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 le opzioni SSV dopo il caricamento dell'annuncio con premio.

// send the request to load the ad.
RewardedAd.Load(_adUnitId, adRequest, (RewardedAd ad, LoadAdError error) =>
{
    // If the operation failed, an error is returned.
    if (error != null || ad == null)
    {
        Debug.LogError("Rewarded ad failed to load an ad with error : " + error);
        return;
    }

    // If the operation completed successfully, no error is returned.
    Debug.Log("Rewarded ad loaded with response : " + ad.GetResponseInfo());

    // Create and pass the SSV options to the rewarded ad.
    var options = new ServerSideVerificationOptions
                          .Builder()
                          .SetCustomData("SAMPLE_CUSTOM_DATA_STRING")
                          .Build()
    ad.SetServerSideVerificationOptions(options);

});

Se vuoi impostare la stringa premio personalizzata, devi farlo prima di mostrare l'annuncio.

Punto chiave: la stringa del premio personalizzata contiene caratteri di escape percentuale e potrebbe richiedere la decodifica quando analizzata dal callback SSV.

Mostrare l'annuncio con premio quando viene richiamato il premio

Quando presenti il tuo annuncio, devi fornire un callback per gestire il premio per l'utente. Gli annunci possono essere mostrati solo una volta per caricamento. Utilizza il metodo CanShowAd() per verificare che l'annuncio sia pronto per essere mostrato.

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

public void ShowRewardedAd()
{
    const string rewardMsg =
        "Rewarded ad rewarded the user. Type: {0}, amount: {1}.";

    if (rewardedAd != null && rewardedAd.CanShowAd())
    {
        rewardedAd.Show((Reward reward) =>
        {
            // TODO: Reward the user.
            Debug.Log(String.Format(rewardMsg, reward.Type, reward.Amount));
        });
    }
}

Ascoltare gli eventi relativi agli annunci con premio

Per personalizzare ulteriormente il comportamento dell'annuncio, puoi collegarti a una serie di eventi del ciclo di vita dell'annuncio: apertura, chiusura e così via. Ascolta questi eventi registrando un delegato come mostrato di seguito.

private void RegisterEventHandlers(RewardedAd ad)
{
    // Raised when the ad is estimated to have earned money.
    ad.OnAdPaid += (AdValue adValue) =>
    {
        Debug.Log(String.Format("Rewarded ad paid {0} {1}.",
            adValue.Value,
            adValue.CurrencyCode));
    };
    // Raised when an impression is recorded for an ad.
    ad.OnAdImpressionRecorded += () =>
    {
        Debug.Log("Rewarded ad recorded an impression.");
    };
    // Raised when a click is recorded for an ad.
    ad.OnAdClicked += () =>
    {
        Debug.Log("Rewarded ad was clicked.");
    };
    // Raised when an ad opened full screen content.
    ad.OnAdFullScreenContentOpened += () =>
    {
        Debug.Log("Rewarded ad full screen content opened.");
    };
    // Raised when the ad closed full screen content.
    ad.OnAdFullScreenContentClosed += () =>
    {
        Debug.Log("Rewarded ad full screen content closed.");
    };
    // Raised when the ad failed to open full screen content.
    ad.OnAdFullScreenContentFailed += (AdError error) =>
    {
        Debug.LogError("Rewarded ad failed to open full screen content " +
                       "with error : " + error);
    };
}

Libera spazio nell'annuncio con premio

Quando hai finito con un RewardedAd, assicurati di chiamare il metodo Destroy() prima di inserire il riferimento:

_rewardedAd.Destroy();

Questo indica al plug-in che l'oggetto non è più utilizzato e che la memoria che occupa può essere recuperata. La mancata chiamata di questo metodo comporta perdite di memoria.

Precarica il successivo annuncio con premio

RewardedAd è un oggetto monouso. Ciò significa che, una volta mostrato un annuncio con premio, l'oggetto non può essere utilizzato di nuovo. Per richiedere un altro annuncio con premio, devi creare un nuovo oggetto RewardedAd.

Per preparare un annuncio con premio per la prossima opportunità di impressione, precarica l'annuncio con premio una volta attivato l'evento annuncio OnAdFullScreenContentClosed o OnAdFullScreenContentFailed.

private void RegisterReloadHandler(RewardedAd ad)
{
    // Raised when the ad closed full screen content.
    ad.OnAdFullScreenContentClosed += () =>
    {
        Debug.Log("Rewarded Ad full screen content closed.");

        // Reload the ad so that we can show another as soon as possible.
        LoadRewardedAd();
    };
    // Raised when the ad failed to open full screen content.
    ad.OnAdFullScreenContentFailed += (AdError error) =>
    {
        Debug.LogError("Rewarded ad failed to open full screen content " +
                       "with error : " + error);

        // Reload the ad so that we can show another as soon as possible.
        LoadRewardedAd();
    };
}

Risorse aggiuntive

• Esempio di HelloWorld: un'implementazione minima di tutti i formati degli annunci.