Anúncios premiados

Os anúncios premiados são aqueles com que os usuários têm a opção de interagir em troca de recompensas no app. Este guia mostra como integrar anúncios premiados da AdMob a um app Unity. Leia algumas histórias de sucesso de clientes: estudo de caso 1, estudo de caso 2.

Pré-requisitos

• Plug-in do Unity 3.16.0 ou mais recente.
• Conclua o guia Primeiros passos.

Criar um objeto de anúncio premiado

Os anúncios premiados são solicitados e exibidos por objetos RewardedAd. A primeira etapa necessária para exibir um anúncio premiado é instanciar um objeto RewardedAd invocando o construtor com o ID do bloco de anúncios a ser usado para carregar o anúncio. Isso é mostrado no snippet de código a seguir:

Para facilitar a integração de anúncios usando o Unity Editor, teste o novo Posicionamento do anúncio Beta.

using UnityEngine.Events;
using UnityEngine;
using GoogleMobileAds.Api;
using GoogleMobileAds.Common;
using UnityEngine.UI;
using System;
using System.Collections.Generic;

public class GoogleMobileAdsDemoScript : MonoBehaviour
{
    private RewardedAd rewardedAd;
    ...

    public void Start()
    {
        ...

        this.rewardedAd = new RewardedAd(adUnitId);
    }
}

Sempre testar com anúncios de teste

Ao criar e testar seus apps, use anúncios de teste em vez de anúncios de produção ativos. Sua conta poderá ser suspensa se isso não for feito.

A maneira mais fácil de carregar anúncios de teste é usar nossos IDs de bloco de anúncios de teste dedicados para anúncios premiados para Android e iOS:

Android

ca-app-pub-3940256099942544/5224354917

iOS

ca-app-pub-3940256099942544/1712485313

Eles foram configurados de modo especial para retornar anúncios de teste a cada solicitação, e você pode usá-los nos seus próprios aplicativos ao programar, testar e depurar. Basta substituí-los pelo ID do seu bloco de anúncios antes de publicar o app.

Para mais informações sobre como os anúncios de teste do SDK de anúncios para dispositivos móveis funcionam, consulte Anúncios de teste.

Carregar um anúncio

Para carregar um anúncio premiado, chame o método loadAd() do objeto RewardedAd. Esse método exige uma instância da AdRequest como argumento.

...
public class GoogleMobileAdsDemoScript : MonoBehaviour
{
    private RewardedAd rewardedAd;
    ...

    public void Start()
    {
        ...

        this.rewardedAd = new RewardedAd(adUnitId);

        // Create an empty ad request.
        AdRequest request = new AdRequest.Builder().Build();
        // Load the rewarded ad with the request.
        this.rewardedAd.LoadAd(request);
    }
}

[Opcional] Validar callbacks de verificação do lado do servidor (SSV)

Apps que exigem dados extras nas chamadas de verificação do lado do servidor precisam usar o recurso de dados personalizados de anúncios premiados. Qualquer valor de string definido em um objeto de anúncio premiado é transmitido para o parâmetro de consulta custom_data do callback do SSV. Se nenhum valor de dados personalizado for definido, o valor do parâmetro de consulta custom_data não estará presente no retorno de chamada SSV.

O exemplo de código a seguir demonstra como definir as opções de SSV depois que o anúncio premiado é carregado.

void HandleRewardedAdLoaded(RewardedAd ad, AdFailedToLoadEventArgs error)
{
    // 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 você quiser definir a string de recompensa personalizada, faça isso antes de exibir o anúncio.

Importante: a string de recompensa personalizada tem percent escape e pode exigir decodificação quando analisada do callback SSV.

Eventos de anúncio

Para personalizar ainda mais o comportamento do anúncio, você pode usar vários eventos no ciclo de vida do anúncio: carregar, abrir, fechar e assim por diante. Detecte esses eventos registrando um delegado para o manipulador de eventos apropriado. O evento mais importante é OnUserEarnedReward, que é chamado quando o usuário é premiado por assistir a um vídeo. Você também pode implementar outros eventos de anúncio, conforme mostrado abaixo.

using GoogleMobileAds.Api;
...
public class GoogleMobileAdsDemoScript : MonoBehaviour
{
    private RewardedAd rewardedAd;
    ...

    public void Start()
    {
        string adUnitId;
        #if UNITY_ANDROID
            adUnitId = "ca-app-pub-3940256099942544/5224354917";
        #elif UNITY_IPHONE
            adUnitId = "ca-app-pub-3940256099942544/1712485313";
        #else
            adUnitId = "unexpected_platform";
        #endif

        this.rewardedAd = new RewardedAd(adUnitId);

        // Called when an ad request has successfully loaded.
        this.rewardedAd.OnAdLoaded += HandleRewardedAdLoaded;
        // Called when an ad request failed to load.
        this.rewardedAd.OnAdFailedToLoad += HandleRewardedAdFailedToLoad;
        // Called when an ad is shown.
        this.rewardedAd.OnAdOpening += HandleRewardedAdOpening;
        // Called when an ad request failed to show.
        this.rewardedAd.OnAdFailedToShow += HandleRewardedAdFailedToShow;
        // Called when the user should be rewarded for interacting with the ad.
        this.rewardedAd.OnUserEarnedReward += HandleUserEarnedReward;
        // Called when the ad is closed.
        this.rewardedAd.OnAdClosed += HandleRewardedAdClosed;

        // Create an empty ad request.
        AdRequest request = new AdRequest.Builder().Build();
        // Load the rewarded ad with the request.
        this.rewardedAd.LoadAd(request);
    }

    public void HandleRewardedAdLoaded(object sender, EventArgs args)
    {
        MonoBehaviour.print("HandleRewardedAdLoaded event received");
    }

    public void HandleRewardedAdFailedToLoad(object sender, AdFailedToLoadEventArgs args)
    {
        MonoBehaviour.print(
            "HandleRewardedAdFailedToLoad event received with message: "
                             + args.Message);
    }

    public void HandleRewardedAdOpening(object sender, EventArgs args)
    {
        MonoBehaviour.print("HandleRewardedAdOpening event received");
    }

    public void HandleRewardedAdFailedToShow(object sender, AdErrorEventArgs args)
    {
        MonoBehaviour.print(
            "HandleRewardedAdFailedToShow event received with message: "
                             + args.Message);
    }

    public void HandleRewardedAdClosed(object sender, EventArgs args)
    {
        MonoBehaviour.print("HandleRewardedAdClosed event received");
    }

    public void HandleUserEarnedReward(object sender, Reward args)
    {
        string type = args.Type;
        double amount = args.Amount;
        MonoBehaviour.print(
            "HandleRewardedAdRewarded event received for "
                        + amount.ToString() + " " + type);
    }
}

O evento OnUserEarnedReward fornece argumentos de eventos especiais. Ela transmite uma instância de Reward com um Type e um Amount que descrevem o prêmio concedido ao usuário:

public void HandleUserEarnedReward(object sender, Reward args)
{
    string type = args.Type;
    double amount = args.Amount;
     MonoBehaviour.print(
          "HandleRewardedAdRewarded event received for "
              + amount.ToString() + " " + type);
}

Aviso:não é recomendável carregar um novo anúncio do bloco de conclusão da solicitação de anúncio quando ele não é carregado. Se for preciso carregar um anúncio do bloco de conclusão de solicitação de anúncio, limite as tentativas de carregamento de anúncio para evitar solicitações contínuas de falha com anúncios em situações como conectividade de rede limitada.

Eventos de anúncio disponíveis

OnAdLoaded

Invocado quando um anúncio termina de carregar.

OnAdFailedToLoad

Invocado quando um anúncio não é carregado. A propriedade Message do AdErrorEventArgs fornecido descreve o tipo de falha que ocorreu.

OnAdOpening

Invocado quando o anúncio é exibido, cobrindo a tela do dispositivo. Esse é um bom lugar para pausar a saída de áudio ou o loop de jogo do app, se necessário.

OnAdFailedToShow

Invocado quando um anúncio não é exibido. A propriedade Message do AdErrorEventArgs fornecido descreve o tipo de falha que ocorreu.

OnUserEarnedReward

Invocado quando um usuário precisa ser recompensado por assistir a um vídeo. O parâmetro Reward descreve o prêmio a ser apresentado ao usuário.

OnAdClosed

Invocado quando o anúncio em vídeo premiado é fechado devido ao usuário tocar no ícone de fechar ou usar o botão "Voltar". Se o app pausou a saída de áudio ou o loop de jogo, este é um ótimo lugar para retomá-lo.

Exibir o anúncio

Antes de exibir um anúncio premiado aos usuários, eles precisam apresentar uma escolha explícita para visualizar o conteúdo do anúncio premiado em troca de uma recompensa. Os anúncios premiados precisam sempre ser uma experiência opcional.

Para exibir um anúncio premiado, verifique o método IsLoaded() para verificar se o carregamento foi concluído e, em seguida, chame show(). Veja como fazer isso a seguir:

private void UserChoseToWatchAd()
{
  if (this.rewardedAd.IsLoaded()) {
    this.rewardedAd.Show();
  }
}

Como usar OnAdClosed para pré-carregar o próximo anúncio premiado

RewardedAd é um objeto de uso único. Isso significa que, depois que um anúncio premiado for exibido, o objeto não poderá ser usado para carregar outro anúncio. Para solicitar outro anúncio premiado, você precisa criar um novo objeto RewardedAd.

Uma prática recomendada é carregar outro anúncio premiado no evento de anúncio OnAdClosed para que o próximo anúncio premiado comece a ser carregado assim que o anterior for dispensado:

...
public class GoogleMobileAdsDemoScript : MonoBehaviour
{
    private RewardedAd rewardedAd;
    ...

    public void CreateAndLoadRewardedAd()
    {
        #if UNITY_ANDROID
            string adUnitId = "ca-app-pub-3940256099942544/5224354917";
        #elif UNITY_IPHONE
            string adUnitId = "ca-app-pub-3940256099942544/1712485313";
        #else
            string adUnitId = "unexpected_platform";
        #endif

        this.rewardedAd = new RewardedAd(adUnitId);

        this.rewardedAd.OnAdLoaded += HandleRewardedAdLoaded;
        this.rewardedAd.OnUserEarnedReward += HandleUserEarnedReward;
        this.rewardedAd.OnAdClosed += HandleRewardedAdClosed;

        // Create an empty ad request.
        AdRequest request = new AdRequest.Builder().Build();
        // Load the rewarded ad with the request.
        this.rewardedAd.LoadAd(request);
    }

...

    public void HandleRewardedAdClosed(object sender, EventArgs args)
    {
        this.CreateAndLoadRewardedAd();
    }
}

Carregar vários anúncios premiados

Para carregar vários anúncios premiados, siga as etapas descritas nas seções criar um objeto de anúncio premiado e carregar um anúncio para cada anúncio que você quer carregar. O snippet de código abaixo demonstra como carregar dois anúncios premiados em duas posições diferentes.

...
public class GoogleMobileAdsDemoScript : MonoBehaviour
{
    private RewardedAd gameOverRewardedAd;
    private RewardedAd extraCoinsRewardedAd;
    ...
    public void Start()
    {
        ...

        this.gameOverRewardedAd = CreateAndLoadRewardedAd(adUnitId);
        this.extraCoinsRewardedAd = CreateAndLoadRewardedAd(adUnitId);
    }

    public RewardedAd CreateAndLoadRewardedAd(string adUnitId)
    {
        RewardedAd rewardedAd = new RewardedAd(adUnitId);

        rewardedAd.OnAdLoaded += HandleRewardedAdLoaded;
        rewardedAd.OnUserEarnedReward += HandleUserEarnedReward;
        rewardedAd.OnAdClosed += HandleRewardedAdClosed;

        // Create an empty ad request.
        AdRequest request = new AdRequest.Builder().Build();
        // Load the rewarded ad with the request.
        rewardedAd.LoadAd(request);
        return rewardedAd;
    }
}

Exemplos

• Exemplo HelloWorld: uma implementação mínima de todos os formatos de anúncio