Aggiunta di un annuncio apertura app AdMob a un'app Unity

1. Introduzione

In questo codelab, implementerai un annuncio apertura app AdMob in un'app Unity.

Cosa creerai

Questo codelab ti guida nell'implementazione di un annuncio apertura app AdMob in un'app Unity utilizzando il plug-in Unity di Google Mobile Ads.

Se riscontri problemi (bug del codice, errori grammaticali, formulazione poco chiara e così via) mentre svolgi questo codelab, segnala il problema utilizzando il link Segnala un errore nell'angolo in basso a sinistra del codelab.

Cosa imparerai a fare

• Come configurare il plug-in Unity di Google Mobile Ads
• Come implementare un annuncio apertura app in un'app Unity

Che cosa ti serve

• Unity 2018.4 o versioni successive
• Xcode 12 o versioni successive e CocoaPods (per il deployment su iOS)

Come valuteresti il tuo livello di esperienza con AdMob?

Principiante Intermedio Avanzato

2. Configura l'ambiente di sviluppo

Scarica il codice

Scarica il codice sorgente Visualizza il repository su GitHub

Dopo aver scaricato il file ZIP, estraine i contenuti. Avrai una cartella denominata admob-appopen-unity-main.

In alternativa, puoi clonare il repository GitHub dalla riga di comando:

$ git clone https://github.com/googlecodelabs/admob-appopen-unity

Il repository contiene due cartelle:

• starter: codice iniziale che creerai in questo codelab.
• complete: codice completato per questo codelab.

3. Configurare l'app AdMob e le unità pubblicitarie

Poiché Unity è un SDK multipiattaforma, devi aggiungere un'app e unità pubblicitarie sia per Android che per iOS in AdMob.

Nota:se vuoi seguire il codelab anziché creare autonomamente una nuova applicazione e unità pubblicitarie, vai alla sezione Utilizzare l'app e le unità pubblicitarie di test di AdMob.

Configurazione per Android

Per la configurazione per Android, devi aggiungere un'app per Android e creare unità pubblicitarie.

Aggiungere un'app per Android

1. Nella console AdMob, fai clic su AGGIUNGI APP dal menu App.
2. Seleziona Android come piattaforma. Quando ti viene chiesto L'app è elencata in uno store supportato?, fai clic su NO.
3. Inserisci AdMob app open ad nel campo del nome dell'app.
4. L'attivazione delle metriche utente non è necessaria per completare questo codelab. Tuttavia, ti consigliamo di farlo perché ti consente di comprendere il comportamento degli utenti in modo più dettagliato. Fai clic su AGGIUNGI per completare la procedura.

Creare un'unità pubblicitaria

1. Seleziona l'app Annuncio di apertura app AdMob (Android) dal menu App nella console AdMob.
2. Fai clic sul menu Unità pubblicitarie.

Fai clic su AGGIUNGI UNITÀ PUBBLICITARIA. Seleziona Apertura app come formato. Inserisci android-appopen nel campo Nome unità pubblicitaria. Fai clic su CREA UNITÀ PUBBLICITARIA per completare la procedura.

Importante:quando crei e testi le tue app, assicurati di utilizzare annunci di prova anziché annunci di produzione live. In caso contrario, il tuo account potrebbe essere sospeso. Per saperne di più sul funzionamento degli annunci di test dell'SDK Mobile Ads, consulta Annunci di test.

In genere, sono necessarie alcune ore prima che una nuova unità pubblicitaria possa pubblicare annunci.

Se vuoi testare immediatamente il comportamento dell'annuncio, utilizza l'ID app e gli ID unità pubblicitaria di prova elencati nelle tabelle ID app/ID unità pubblicitaria Android e ID app/ID unità pubblicitaria iOS.

Configurazione per iOS

Per la configurazione per iOS, devi aggiungere un'app per iOS e creare unità pubblicitarie.

Aggiungere un'app per iOS

1. Nella console AdMob, fai clic su AGGIUNGI APP dal menu App.
2. Seleziona iOS come piattaforma. Quando ti viene chiesto L'app è elencata in uno store supportato?, fai clic su NO.
3. Inserisci AdMob app open ad nel campo del nome dell'app.
4. L'attivazione delle metriche utente non è necessaria per completare questo codelab. Tuttavia, ti consigliamo di farlo perché ti consente di comprendere il comportamento degli utenti in modo più dettagliato. Fai clic su AGGIUNGI per completare la procedura.

Creare un'unità pubblicitaria

1. Seleziona l'app Annunci in linea AdMob (iOS) dal menu App nella console AdMob.
2. Fai clic sul menu Unità pubblicitarie.

Fai clic su AGGIUNGI UNITÀ PUBBLICITARIA. Seleziona Apertura app come formato. Inserisci ios-appopen nel campo Nome unità pubblicitaria. Fai clic su CREA UNITÀ PUBBLICITARIA per completare la procedura.

Importante:quando crei e testi le tue app, assicurati di utilizzare annunci di prova anziché annunci di produzione live. In caso contrario, il tuo account potrebbe essere sospeso. Per saperne di più sul funzionamento degli annunci di test dell'SDK Mobile Ads, consulta Annunci di test.

In genere, sono necessarie alcune ore prima che una nuova unità pubblicitaria possa pubblicare annunci.

Se vuoi testare immediatamente il comportamento dell'annuncio, utilizza l'ID app di test e gli ID unità pubblicitaria elencati nella tabella seguente.

(Facoltativo) Utilizza l'app e le unità pubblicitarie di test di AdMob

Se vuoi seguire il codelab anziché creare autonomamente una nuova applicazione e nuove unità pubblicitarie, puoi utilizzare l'ID app AdMob di test e gli ID unità pubblicitaria elencati nelle tabelle seguenti.

ID app/unità pubblicitaria Android

Elemento	ID app/ID unità pubblicitaria
ID app monetizzata con AdMob	ca-app-pub-3940256099942544~3347511713
ID unità pubblicitaria	ca-app-pub-3940256099942544/3419835294

ID app/unità pubblicitaria per iOS

Elemento	ID app/ID unità pubblicitaria
ID app monetizzata con AdMob	ca-app-pub-3940256099942544~1458002511
ID unità pubblicitaria	ca-app-pub-3940256099942544/5662855259

Per saperne di più sugli annunci di prova, consulta la documentazione per gli sviluppatori relativa agli annunci di prova per Android e agli annunci di prova per iOS.

4. Aggiungi il plug-in Google Mobile Ads Unity

L'integrazione del plug-in Unity di Google Mobile Ads è il primo passo per mostrare gli annunci AdMob e generare entrate.

Scaricare il plug-in Unity per Mobile Ads

Il plug-in Google Mobile Ads Unity consente agli sviluppatori Unity di pubblicare facilmente Google Mobile Ads su app per Android e iOS. Il plug-in fornisce un'interfaccia C# per richiedere gli annunci, utilizzata dagli script C# nel progetto Unity.

Utilizza il link di seguito per scaricare il pacchetto Unity per il plug-in.

Scarica il plug-in

Apri il progetto iniziale

1. Avvia Unity Hub.
2. Nella scheda Progetti, fai clic sul pulsante AGGIUNGI.
3. Vai alla cartella in cui hai estratto il codice scaricato nel passaggio Configura l'ambiente di sviluppo.
4. Apri la cartella starter.
5. Vedrai il progetto starter nell'elenco dei progetti. Fai clic sul progetto per aprirlo in Unity Editor.

Importare il plug-in Unity di Mobile Ads

1. Nell'editor Unity, seleziona Assets > Import Package > Custom Package (Asset > Importa pacchetto > Pacchetto personalizzato) dal menu.
2. Seleziona il file GoogleMobileAds-{VERSION}.unitypackage che hai scaricato nel passaggio precedente.
3. Assicurati che tutti i file siano selezionati e fai clic su Importa.

Impostare l'ID app AdMob

1. Nell'editor Unity, seleziona Asset > Google Mobile Ads > Impostazioni dal menu.
2. Inserisci l'ID app AdMob per Android e iOS in ogni campo. Se vuoi seguire il codelab anziché creare autonomamente una nuova applicazione e nuove unità pubblicitarie, inserisci l'ID app AdMob di test nel seguente modo.

Importante:se non inserisci l'ID app AdMob, l'app si arresta in modo anomalo.

5. Crea una classe di utilità

Crea una nuova classe denominata AppOpenAdManager nella cartella Script. Questa classe gestisce una variabile di istanza per tenere traccia di un annuncio caricato e dell'ID unità pubblicitaria per ogni piattaforma.

AppOpenAdManager.cs

using System;
using GoogleMobileAds.Api;
using UnityEngine;

public class AppOpenAdManager
{
#if UNITY_ANDROID
    // Test ad unit ID: ca-app-pub-3940256099942544/3419835294
    private const string AD_UNIT_ID = "<YOUR_ANDROID_APPOPEN_AD_UNIT_ID>";
#elif UNITY_IOS
    // Test ad unit ID: ca-app-pub-3940256099942544/5662855259
    private const string AD_UNIT_ID = "<YOUR_IOS_APPOPEN_AD_UNIT_ID>";
#else
    private const string AD_UNIT_ID = "unexpected_platform";
#endif

    private static AppOpenAdManager instance;

    private AppOpenAd ad;

    private bool isShowingAd = false;

    public static AppOpenAdManager Instance
    {
        get
        {
            if (instance == null)
            {
                instance = new AppOpenAdManager();
            }

            return instance;
        }
    }

    private bool IsAdAvailable
    {
        get
        {
            return ad != null;
        }
    }

    public void LoadAd()
    {
        // TODO: Load an app open ad.
    }
}

Caricare un annuncio

Il caricamento di un annuncio viene eseguito utilizzando il metodo statico AppOpenAd.LoadAd(). Il metodo di caricamento richiede un ID unità pubblicitaria, una modalità ScreenOrientation, un oggetto AdRequest e un gestore di completamento che viene chiamato quando il caricamento dell'annuncio ha esito positivo o negativo.

L'oggetto AppOpenAd caricato viene fornito come parametro nel gestore di completamento. Implementa il metodo LoadAd() come segue.

AppOpenAdManager.cs

public class AppOpenAdManager
{
    ...

    public void LoadAd()
    {
        AdRequest request = new AdRequest.Builder().Build();

        // Load an app open ad for portrait orientation
        AppOpenAd.LoadAd(AD_UNIT_ID, ScreenOrientation.Portrait, request, ((appOpenAd, error) =>
        {
            if (error != null)
            {
                // Handle the error.
                Debug.LogFormat("Failed to load the ad. (reason: {0})", error.LoadAdError.GetMessage());
                return;
            }

            // App open ad is loaded.
            ad = appOpenAd;
        }));
    }
}

Mostra l'annuncio

Prima di mostrare l'annuncio, registrati per ogni gestore di eventi in modo da ascoltare ogni evento dell'annuncio.

AppOpenAdManager.cs

public class AppOpenAdManager
{
    ...

    public void ShowAdIfAvailable()
    {
        if (!IsAdAvailable || isShowingAd)
        {
            return;
        }

        ad.OnAdDidDismissFullScreenContent += HandleAdDidDismissFullScreenContent;
        ad.OnAdFailedToPresentFullScreenContent += HandleAdFailedToPresentFullScreenContent;
        ad.OnAdDidPresentFullScreenContent += HandleAdDidPresentFullScreenContent;
        ad.OnAdDidRecordImpression += HandleAdDidRecordImpression;
        ad.OnPaidEvent += HandlePaidEvent;

        ad.Show();
    }

    private void HandleAdDidDismissFullScreenContent(object sender, EventArgs args)
    {
        Debug.Log("Closed app open ad");
        // Set the ad to null to indicate that AppOpenAdManager no longer has another ad to show.
        ad = null;
        isShowingAd = false;
        LoadAd();
    }

    private void HandleAdFailedToPresentFullScreenContent(object sender, AdErrorEventArgs args)
    {
        Debug.LogFormat("Failed to present the ad (reason: {0})", args.AdError.GetMessage());
        // Set the ad to null to indicate that AppOpenAdManager no longer has another ad to show.
        ad = null;
        LoadAd();
    }

    private void HandleAdDidPresentFullScreenContent(object sender, EventArgs args)
    {
        Debug.Log("Displayed app open ad");
        isShowingAd = true;
    }

    private void HandleAdDidRecordImpression(object sender, EventArgs args)
    {
        Debug.Log("Recorded ad impression");
    }

    private void HandlePaidEvent(object sender, AdValueEventArgs args)
    {
        Debug.LogFormat("Received paid event. (currency: {0}, value: {1}",
                args.AdValue.CurrencyCode, args.AdValue.Value);
    }
}

Considerare la scadenza degli annunci

I riferimenti agli annunci nell'apertura dell'app scadranno dopo quattro ore. Gli annunci visualizzati più di quattro ore dopo l'ora della richiesta non saranno più validi e potrebbero non generare entrate.

Per assicurarti di non mostrare un annuncio scaduto, modifica la proprietà IsAdAvailable in AppOpenAdManager, che controlla il tempo trascorso dal caricamento dell'annuncio. Quindi, utilizza questo metodo per verificare se l'annuncio è ancora valido.

AppOpenAdManager.cs

public class AppOpenAdManager
{
    ...

    // TODO: Add loadTime field
    private DateTime loadTime;

    private bool IsAdAvailable
    {
        get
        {
            // TODO: Consider ad expiration
            return ad != null && (System.DateTime.UtcNow - loadTime).TotalHours < 4;
        }
    }

    public void LoadAd()
    {
        if (IsAdAvailable)
        {
            return;
        }

        AdRequest request = new AdRequest.Builder().Build();
        AppOpenAd.LoadAd(AD_UNIT_ID, ScreenOrientation.Portrait, request, ((appOpenAd, error) =>
        {
            if (error != null)
            {
                Debug.LogFormat("Failed to load the ad. (reason: {0})", error.LoadAdError.GetMessage());
                return;
            }

            ad = appOpenAd;
            Debug.Log("App open ad loaded");

            // TODO: Keep track of time when the ad is loaded.
            loadTime = DateTime.UtcNow;
        }));
    }
}

6. Aggiorna la scena per caricare/mostrare l'annuncio

Aggiorna il metodo Start() nella classe MainScene per caricare un annuncio di apertura dell'app all'avvio della scena.

Per ricevere una notifica degli eventi di primo piano dell'app, ti consigliamo di ascoltare il singleton AppStateEventNotifier. Implementando il delegato AppStateEventNotifier.AppStateChanged, la tua app riceverà avvisi relativi agli eventi di avvio e messa in primo piano dell'app e potrà mostrare l'annuncio.

MainScene.cs

using GoogleMobileAds.Api;
using GoogleMobileAds.Common;
using UnityEngine;

public class MainScene : MonoBehaviour
{
    public void Start()
    {
        // TODO: Request an app open ad.
        MobileAds.Initialize((initStatus) =>
        {
            AppOpenAdManager.Instance.LoadAd();
            AppStateEventNotifier.AppStateChanged += OnAppStateChanged;
        });
    }

    public void OnAppStateChanged(AppState state)
    {
        if (state == AppState.Foreground)
        {
            // TODO: Show an app open ad if available.
            AppOpenAdManager.Instance.ShowAdIfAvailable();
        }
    }
}

Importante: AppStateEventNotifier è consigliato perché OnApplicationPause fornisce segnali di primo piano e di sfondo falsi quando l'app mostra un annuncio a schermo intero.

Nota: gli annunci apertura app possono essere mostrati quando l'utente torna all'app da un'altra app (ad esempio, per scegliere una foto dalla galleria), perché anche questo è considerato un evento di "cambio app". È consigliabile disattivare/attivare gli annunci apertura app per evitare che vengano mostrati nel mezzo di un flusso utente importante.

È tutto. Crea ed esegui il progetto su un dispositivo o un emulatore. Una volta avviata l'app, attendi qualche secondo per consentire il caricamento completo dell'annuncio.

Dopodiché, quando torni all'app da altre app/schermata Home, l'annuncio di apertura dell'app verrà visualizzato come di seguito.

7. Operazione completata.

Hai completato il codelab. Puoi trovare il codice completato per questo codelab nella cartella complete.