Adicionar um anúncio de abertura do app AdMob a um app Unity

1. Apresentação

Neste codelab, você vai implementar um anúncio de abertura do app AdMob em um app Unity.

O que você criará

Este codelab mostra como implementar um anúncio de abertura do app AdMob em um app Unity usando o plug-in de anúncios para dispositivos móveis do Google para Unity.

Use o link Informar um erro no canto inferior esquerdo da codelab para reportar problemas (bugs no código, erros gramaticais, enunciados confusos, entre outros) que você tiver durante este codelab.

O que você aprenderá

• Como configurar o plug-in dos anúncios para dispositivos móveis do Google para Unity
• Como implementar um anúncio de abertura do app em um app Unity

Recursos necessários

• Unity 2018.4 ou mais recente
• Xcode 12 ou mais recente e CocoaPods (para implantação no iOS)

Qual é seu nível de experiência com a AdMob?

Iniciante Intermediário Proficiente

2. Configurar o ambiente de desenvolvimento

Fazer o download do código

Fazer o download do código-fonte Visualizar o repositório no GitHub

Faça o download e extraia o conteúdo do arquivo ZIP. Nele, você vai encontrar a pasta admob-appopen-unity-main.

Se preferir, clone o repositório do GitHub encontrado na linha de comando:

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

O repositório contém duas pastas:

• starter: código inicial que você vai criar neste codelab.
• complete: código completo para este codelab.

3. Configurar o app e os blocos de anúncios da AdMob

Como o Unity é um SDK de multiplataforma, você precisa adicionar um app e blocos de anúncios para Android e iOS na AdMob.

Observação: se você quiser seguir o codelab em vez de criar um novo app e blocos de anúncios por conta própria, acesse a seção Usar o app e os blocos de anúncios de teste da AdMob.

Configuração para Android

Adicione um app Android e crie blocos de anúncios.

Adicionar um app Android

1. No Console da AdMob, clique em ADICIONAR APP no menu Apps.
2. Selecione Android como a plataforma. Quando a mensagem O app está disponível em uma app store compatível? aparecer, clique em NÃO.
3. Digite AdMob app open ad no campo do nome do app.
4. Não é preciso ativar as métricas do usuário para concluir este codelab. No entanto, recomendamos que você faça isso para entender melhor o comportamento do usuário. Clique em ADICIONAR para concluir o processo.

Criar um bloco de anúncios

1. Selecione Anúncio de abertura do app AdMob (Android) no menu Apps do console da AdMob.
2. Clique no menu Blocos de anúncios.

Clique em ADICIONAR BLOCO DE ANÚNCIOS. Selecione Abertura do app como o formato. Insira android-appopen no campo Nome do bloco de anúncios. Clique em CRIAR BLOCO DE ANÚNCIOS para concluir o processo.

Importante: ao criar e testar seus apps, use anúncios de teste em vez de publicidade ativa e em produção. Se isso não for feito, sua conta poderá ser suspensa. Para mais informações sobre como os anúncios de teste do SDK para dispositivos móveis funcionam, consulte Anúncios de teste.

Geralmente, leva algumas horas para que um novo bloco comece a veicular anúncios.

Se você quiser testar o comportamento do anúncio imediatamente, use os IDs de teste listados nas tabelas de ID do app Android/bloco de anúncios e ID do app iOS/bloco de anúncios.

Configuração para iOS

Adicione um app iOS e crie blocos de anúncios.

Adicionar um app iOS

1. No Console da AdMob, clique em ADICIONAR APP no menu Apps.
2. Selecione iOS como a plataforma. Quando a mensagem O app está disponível em uma app store compatível? aparecer, clique em NÃO.
3. Digite AdMob app open ad no campo do nome do app.
4. Não é preciso ativar as métricas do usuário para concluir este codelab. No entanto, recomendamos que você faça isso para entender melhor o comportamento do usuário. Clique em ADICIONAR para concluir o processo.

Criar um bloco de anúncios

1. Selecione o app Anúncios inline da AdMob (iOS) no menu Apps do console da AdMob.
2. Clique no menu Blocos de anúncios.

Clique em ADICIONAR BLOCO DE ANÚNCIOS. Selecione Abertura do app como o formato. Insira ios-appopen no campo Nome do bloco de anúncios. Clique em CRIAR BLOCO DE ANÚNCIOS para concluir o processo.

Importante: ao criar e testar seus apps, use anúncios de teste em vez de publicidade ativa e em produção. Se isso não for feito, sua conta poderá ser suspensa. Para mais informações sobre como os anúncios de teste do SDK para dispositivos móveis funcionam, consulte Anúncios de teste.

Geralmente, leva algumas horas para que um novo bloco comece a veicular anúncios.

Se você quiser testar o comportamento do anúncio imediatamente, use os IDs de app e de bloco de anúncios de teste listados na tabela a seguir.

Opcional: usar o app e os blocos de anúncios de teste da AdMob

Se você quiser seguir o codelab em vez de criar um novo app e blocos de anúncios por conta própria, use os IDs do app AdMob e dos blocos de anúncios de teste listados na tabela a seguir.

ID do app Android/bloco de anúncios

Item	ID do app/bloco de anúncios
ID do app AdMob	ca-app-pub-3940256099942544~3347511713
ID do bloco de anúncios	ca-app-pub-3940256099942544/3419835294

ID do app iOS/bloco de anúncios

Item	ID do app/bloco de anúncios
ID do app AdMob	ca-app-pub-3940256099942544~1458002511
ID do bloco de anúncios	ca-app-pub-3940256099942544/5662855259

Para mais informações sobre anúncios de teste, consulte a documentação para desenvolvedores no links Anúncios de teste para Android e Anúncios de teste para iOS.

4. Adicionar o plug-in de anúncios para dispositivos móveis do Google para Unity

A integração do plug-in dos anúncios para dispositivos móveis do Google para Unity é a primeira etapa para veicular anúncios da AdMob e gerar receita.

Fazer o download do plug-in dos anúncios para dispositivos móveis para Unity

Com o plug-in dos anúncios para dispositivos móveis do Google para Unity, os desenvolvedores veiculam anúncios do Google com facilidade em apps Android e iOS. O plug-in fornece uma interface em C# para solicitar anúncios que é usada por scripts C# no seu projeto do Unity.

Use o link abaixo para fazer o download do pacote do Unity para o plug-in.

Fazer o download do plug-in

Abrir o projeto "starter"

1. Inicie o Unity Hub.
2. Na guia Projetos, clique no botão ADICIONAR.
3. Navegue até a pasta em você extraiu o código do download feito na etapa Configurar o ambiente de desenvolvimento.
4. Abra a pasta starter.
5. O projeto starter estará na lista de projetos. Clique nele para abrir no editor do Unity.

Importar o plug-in dos anúncios para dispositivos móveis para Unity

1. No editor do Unity, selecione Assets > Import Package > Custom Package no menu.
2. Selecione o GoogleMobileAds-{VERSION}.unitypackage que você salvou na etapa anterior.
3. Verifique se todos os arquivos estão selecionados e clique em Import.

Definir o ID do app AdMob

1. No editor do Unity, selecione Assets > Google Mobile Ads > Settings no menu.
2. Insira o ID do app AdMob para Android e iOS em cada campo. Se você quiser seguir o codelab em vez de criar um novo app e blocos de anúncios por conta própria, insira o ID do app AdMob de teste conforme mostrado abaixo.

Importante: se o ID do app AdMob não for inserido, o app não vai funcionar.

5. Criar uma classe de utilitários

Crie uma nova classe com o nome AppOpenAdManager na pasta Scripts. Esta classe gerencia uma variável de instância para acompanhar um anúncio carregado e o ID do bloco de anúncios de cada plataforma.

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.
    }
}

Carregar um anúncio

É possível carregar um anúncio usando o método estático AppOpenAd.LoadAd(). O método de carregamento requer um ID do bloco de anúncios, um modo ScreenOrientation, um objeto AdRequest e um gerenciador de conclusão que é ativado quando o carregamento do anúncio é concluído ou apresenta falha.

O objeto AppOpenAd carregado é fornecido como um parâmetro no gerenciador de conclusão. Implemente o método LoadAd() conforme abaixo.

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;
        }));
    }
}

Mostrar o anúncio

Antes de veicular o anúncio, faça o registro de cada manipulador de eventos para acompanhar o evento de anúncio.

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);
    }
}

Considerar a validade dos anúncios

As referências aos anúncios na abertura do app expiram após quatro horas. Os anúncios renderizados mais de quatro horas após o momento da solicitação não são mais válidos e talvez não gerem receita.

Para que um anúncio expirado não seja veiculado, modifique a propriedade IsAdAvailable para AppOpenAdManager, que verifica há quanto tempo o anúncio foi carregado. Depois, use esse método para verificar se o anúncio continua válido.

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. Atualizar a cena para carregar/mostrar o anúncio

Atualize o método Start() na classe MainScene para carregar um anúncio de abertura do app quando a cena começar.

Para receber notificações sobre eventos em primeiro plano do app, recomendamos que você consulte o Singleton do AppStateEventNotifier. Quando implementar o delegado AppStateEventNotifier.AppStateChanged, seu app será alertado sobre a inicialização do app e os eventos em primeiro plano e conseguirá veicular o anúncio.

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 : o uso de AppStateEventNotifier é recomendado porque o OnApplicationPause vai fornecer indicadores de primeiro e segundo plano falsos quando o app mostrar um anúncio de tela cheia.

Observação: os anúncios de abertura do app podem aparecer quando a pessoa acessa o app em outro app (por exemplo, para escolher uma foto da galeria) porque isso também é considerado um evento de "troca de app". É recomendável desativar/ativar os anúncios de abertura do app para evitar que sejam veiculados no meio de um fluxo importante de um usuário.

Pronto! Crie e execute o projeto em um dispositivo ou emulador. Após iniciar o app, aguarde alguns segundos até que o anúncio seja carregado por completo.

Depois disso, quando você voltar para o app da tela inicial e de outros apps, o anúncio de abertura do app vai aparecer como mostrado abaixo.

7. Pronto!

Você concluiu o codelab. O código final deste codelab está na pasta complete.