Annunci banner

Le visualizzazioni banner sono annunci illustrati o di testo rettangolari che occupano uno spazio sullo schermo. Rimangono sullo schermo durante l'interazione degli utenti con l'app e possono aggiornarsi automaticamente dopo un determinato periodo di tempo. Se non hai mai utilizzato la pubblicità per il mobile, sono un ottimo punto di partenza.

Questa guida mostra come integrare le visualizzazioni dei banner in un'app Unity. Oltre agli snippet di codice e alle istruzioni, include anche informazioni su come impostare correttamente le dimensioni dei banner e link a risorse aggiuntive.

Prerequisiti

• Completa la Guida introduttiva.

Esegui sempre test con annunci di prova

Il seguente codice di esempio contiene un ID unità pubblicitaria che puoi utilizzare per richiedere annunci di prova. È stato configurato appositamente per restituire annunci di prova anziché annunci di produzione per ogni richiesta, il che lo rende sicuro da usare.

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

/21775744923/example/adaptive-banner

Inizializza l'SDK Mobile Ads

Prima di caricare gli annunci, fai in modo che l'app inizili 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 il callback prima di caricare gli annunci, in quanto questo garantirà l'inizializzazione di tutti gli adattatori di mediazione.

Esempio di BannerView

Il codice di esempio riportato di seguito illustra come utilizzare la visualizzazione del banner. Nell'esempio, crei un'istanza di una visualizzazione banner, utilizzi un AdManagerAdRequest per caricare un annuncio nella visualizzazione banner e poi estendi le sue funzionalità gestendo gli eventi del ciclo di vita.

Creare una visualizzazione banner

Il primo passaggio per utilizzare una visualizzazione banner è creare un'istanza di una visualizzazione banner in uno script C# associato a un GameObject.

  // This ad unit is configured to always serve test ads.
  private string _adUnitId = "/21775744923/example/adaptive-banner";

  AdManagerBannerView _bannerView;

  /// <summary>
  /// Creates a 320x50 banner view at top of the screen.
  /// </summary>
  public void CreateBannerView()
  {
      Debug.Log("Creating banner view");

      // If we already have a banner, destroy the old one.
      if (_bannerView != null)
      {
          DestroyAd();
      }

      // Create a 320x50 banner at top of the screen
      _bannerView = new AdManagerBannerView(_adUnitId, AdSize.Banner, AdPosition.Top);
  }

Il costruttore di un AdManagerBannerView ha i seguenti parametri:

• adUnitId: l'ID unità pubblicitaria da cui deve caricare gli annunciAdManagerBannerView.
• AdSize: le dimensioni dell'annuncio che vuoi utilizzare. Per maggiori dettagli, consulta la sezione Dimensioni dei banner.
• AdPosition: la posizione in cui devono essere posizionate le visualizzazioni del banner. L'enum AdPosition elenca i valori validi della posizione dell'annuncio.

Tieni presente come vengono utilizzate unità pubblicitarie diverse, a seconda della piattaforma. Devi utilizzare un'unità pubblicitaria per iOS per effettuare richieste di annunci su iOS e un'unità pubblicitaria per Android per effettuare richieste su Android.

(Facoltativo) Crea una visualizzazione del banner con una posizione personalizzata

Per un maggiore controllo sulla posizione di un AdManagerBannerView sullo schermo rispetto a quanto offerto dai valori AdPosition, utilizza il costruttore con le coordinate x e y come parametri:

// Create a 320x50 banner views at coordinate (0,50) on screen.
_bannerView = new AdManagerBannerView(_adUnitId, AdSize.Banner, 0, 50);

L'angolo in alto a sinistra di AdManagerBannerView è posizionato in base ai valori x e y passati al costruttore, dove l'origine è l'angolo in alto a sinistra dello schermo.

(Facoltativo) Crea una visualizzazione del banner con una dimensione personalizzata

Oltre a utilizzare una costante AdSize, puoi anche specificare una dimensione personalizzata per l'annuncio:

// Use the AdSize argument to set a custom size for the ad.
AdSize adSize = new AdSize(250, 250);
_bannerView = new AdManagerBannerView(_adUnitId, adSize, AdPosition.Bottom);

(Facoltativo) Più dimensioni degli annunci

Ad Manager ti consente di specificare più dimensioni degli annunci che potrebbero essere idonee alla pubblicazione in un AdManagerBannerView. Prima di implementare questa funzionalità nell'SDK, crea un elemento pubblicitario che abbia come target le stesse unità pubblicitarie associate a creatività di dimensioni diverse.

Nell'app, passa più parametri AdSize a ValidAdSizes:

var adView = new AdManagerBannerView(_adUnitId, AdSize.Banner, AdPosition.Top);
adView.ValidAdSizes = new List<AdSize>
{
    AdSize.Banner, new AdSize(120, 20), new AdSize(250, 250),
};

Se AdManagerAdView cambia dimensione al momento dell'aggiornamento, il layout dovrebbe essere in grado di adattarsi automaticamente alle nuove dimensioni. AdManagerAdView assume per impostazione predefinita la dimensione passata nel primo parametro fino al ritorno dell'annuncio successivo.

Caricare un annuncio banner

Dopo aver impostato AdManagerBannerView, carica un annuncio con il metodo LoadAd() nella classe AdManagerBannerView. Richiede un parametro che contiene informazioni di runtime, ad esempio informazioni sul targeting, etichette di esclusione e l'ID fornito dall'editore.

/// <summary>
/// Creates the banner view and loads a banner ad.
/// </summary>
public void LoadAd()
{
    // create an instance of a banner view first.
    if(_bannerView == null)
    {
        CreateAdManagerBannerView();
    }

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

    // send the request to load the ad.
    Debug.Log("Loading banner ad.");
    _bannerView.LoadAd(adRequest);
}

Suggerimento: puoi utilizzare le chiamate di caricamento degli annunci per creare una cache di annunci pre caricati prima di intenderne la pubblicazione, in modo che gli annunci possano essere mostrati senza latenza quando necessario. Poiché gli annunci scadono dopo un'ora, devi svuotare questa cache e ricaricare con nuovi annunci ogni ora.

Ascolta gli eventi di visualizzazione del banner

Per personalizzare il comportamento dell'annuncio, puoi collegarti a una serie di eventi nel ciclo di vita dell'annuncio, come il caricamento, l'apertura o la chiusura. Per ascoltare questi eventi, registra un delegato:

/// <summary>
/// listen to events the banner view may raise.
/// </summary>
private void ListenToAdEvents()
{
    // Raised when an ad is loaded into the banner view.
    _bannerView.OnBannerAdLoaded += () =>
    {
        Debug.Log("Banner view loaded an ad with response : "
            + _bannerView.GetResponseInfo());
    };
    // Raised when an ad fails to load into the banner view.
    _bannerView.OnBannerAdLoadFailed += (LoadAdError error) =>
    {
        Debug.LogError("Banner view failed to load an ad with error : "
            + error);
    };
    // Raised when the ad is estimated to have earned money.
    _bannerView.OnAdPaid += (AdValue adValue) =>
    {
        Debug.Log(String.Format("Banner view paid {0} {1}.",
            adValue.Value,
            adValue.CurrencyCode));
    };
    // Raised when an impression is recorded for an ad.
    _bannerView.OnAdImpressionRecorded += () =>
    {
        Debug.Log("Banner view recorded an impression.");
    };
    // Raised when a click is recorded for an ad.
    _bannerView.OnAdClicked += () =>
    {
        Debug.Log("Banner view was clicked.");
    };
    // Raised when an ad opened full screen content.
    _bannerView.OnAdFullScreenContentOpened += () =>
    {
        Debug.Log("Banner view full screen content opened.");
    };
    // Raised when the ad closed full screen content.
    _bannerView.OnAdFullScreenContentClosed += () =>
    {
        Debug.Log("Banner view full screen content closed.");
    };
}

Elimina la visualizzazione del banner

Al termine dell'utilizzo della visualizzazione del banner, assicurati di chiamare Destroy() per rilasciare le risorse.

/// <summary>
/// Destroys the banner view.
/// </summary>
public void DestroyAd()
{
    if (_bannerView != null)
    {
        Debug.Log("Destroying banner view.");
        _bannerView.Destroy();
        _bannerView = null;
    }
}

È tutto. La tua app è ora pronta per mostrare gli annunci banner.

Aggiornare un annuncio

Se hai configurato l'aggiornamento dell'unità pubblicitaria, non devi richiedere un altro annuncio quando non riesce a caricarsi. L'SDK Google Mobile Ads rispetta qualsiasi frequenza di aggiornamento specificata nell'interfaccia utente di Ad Manager. Se non hai attivato il aggiornamento, invia una nuova richiesta. Per ulteriori dettagli sull'aggiornamento delle unità pubblicitarie, ad esempio sull'impostazione di una frequenza di aggiornamento, consulta Frequenza di aggiornamento degli annunci nelle app mobile.

Nota: quando imposti una frequenza di aggiornamento nell'interfaccia utente di Ad Manager, l'aggiornamento automatico avviene solo se il banner è visibile sullo schermo.

Dimensioni dei banner

La tabella seguente elenca le dimensioni standard dei banner.

Dimensioni in dp (LxH)	Descrizione	Disponibilità	Costante AdSize
320 x 50	Banner standard	Cellulari e tablet	BANNER
320 x 100	Banner grande	Cellulari e tablet	LARGE_BANNER
300 x 250	Rettangolo medio IAB	Cellulari e tablet	MEDIUM_RECTANGLE
468 x 60	Banner IAB a grandezza naturale	Tablet	FULL_BANNER
728 x 90	Classifica IAB	Tablet	LEADERBOARD
Larghezza fornita x Altezza adattativa	Banner adattivo	Cellulari e tablet	N/D
Larghezza dello schermo x 32|50|90	Banner intelligenti	Cellulari e tablet	SMART_BANNER
Scopri di più sui banner adattivi, destinati a sostituire i banner intelligenti.

Nota: se un'app per Android tenta di caricare un banner troppo grande per il relativo layout, l'SDK non lo mostrerà, registrando invece un messaggio di errore.

Eventi app

Gli eventi app ti consentono di creare annunci che possono inviare messaggi al codice dell'app. L'app può quindi eseguire azioni in base a questi messaggi.

Puoi ascoltare eventi app specifici di Ad Manager utilizzando AppEvent. Questi eventi possono verificarsi in qualsiasi momento durante il ciclo di vita dell'annuncio, anche prima della chiamata al caricamento.

namespace GoogleMobileAds.Api.AdManager;

/// The App event message sent from the ad.
public class AppEvent
{
    // Name of the app event.
    string Name;
    // Argument passed from the app event.
    string Value;
}

OnAppEventReceived viene attivato quando si verifica un evento dell'app in un annuncio. Ecco un esempio di come gestire questo evento nel codice:

_bannerview.OnAppEventReceived += (AppEvent args) =>
{
    Debug.Log($"Received app event from the ad: {args.Name}, {args.Value}.");
};

Ecco un esempio che mostra come modificare il colore di sfondo dell'app in base a un evento app con un nome di colore:

_bannerview.OnAppEventReceived += (AppEvent args) =>
{
  if (args.Name == "color")
  {
    Color color;
    if (ColorUtility.TryParseColor(arg.Value, out color))
    {
      gameObject.GetComponent<Renderer>().material.color = color;
    }
  }
};

Ecco la creatività corrispondente che invia l'evento relativo all'app di colore:

<html>
<head>
  <script src="//www.gstatic.com/afma/api/v1/google_mobile_app_ads.js"></script>
  <script>
    document.addEventListener("DOMContentLoaded", function() {
      // Send a color=green event when ad loads.
      admob.events.dispatchAppEvent("color", "green");

      document.getElementById("ad").addEventListener("click", function() {
        // Send a color=blue event when ad is clicked.
        admob.events.dispatchAppEvent("color", "blue");
      });
    });
  </script>
  <style>
    #ad {
      width: 320px;
      height: 50px;
      top: 0px;
      left: 0px;
      font-size: 24pt;
      font-weight: bold;
      position: absolute;
      background: black;
      color: white;
      text-align: center;
    }
  </style>
</head>
<body>
  <div id="ad">Carpe diem!</div>
</body>
</html>

Risorse aggiuntive

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