Dar os primeiros passos

Este guia mostra como usar o complemento de anúncios nativos para implementar anúncios nativos da AdMob em um app do Unity, além de outras considerações importantes.

Os anúncios nativos correspondem à forma e à função da experiência do usuário em que estão inseridos. Eles também correspondem ao design visual do app em que estão inseridos. Com o formato de anúncios nativos da AdMob, os editores podem renderizar anúncios que combinam com o conteúdo. É possível usar essa tecnologia para implementar renderizações altamente personalizadas que aproveitam ao máximo o código nativo em apps do Unity.

Os anúncios nativos são exibidos usando os mesmos tipos de GameObjects com que você já está criando seus apps e podem ser formatados para corresponder ao design visual da experiência do usuário em que residem. Quando um anúncio nativo é carregado, seu app recebe um objeto nativo que contém os recursos dele, e o app Unity (em vez do SDK) os exibe.

Pré-requisitos

Carregar formatos de anúncio nativo

Os anúncios nativos são carregados por meio da classe AdLoader, que tem a própria classe AdLoader.Builder para personalizá-la durante a criação. O método ForNativeAd() configura o AdLoader para processar anúncios nativos.

private void RequestNativeAd() {
    AdLoader adLoader = new AdLoader.Builder(INSERT_AD_UNIT_HERE)
        .ForNativeAd()
        .Build();
}

Registrar-se em eventos de anúncio do AdLoader

Para receber uma notificação quando um anúncio nativo for carregado ou falhar, adicione delegados à classe AdLoader para os eventos listados abaixo.

OnSitemapLoaded

Invocado quando um anúncio nativo é carregado. É necessário ter um delegado para que esse evento acesse o anúncio carregado.

OnAdFailedToLoad

Invocado quando um anúncio nativo não é carregado.

Carregar o anúncio

Quando terminar de criar um AdLoader, chame o método LoadAd() para solicitar um anúncio:

adLoader.LoadAd(new AdRequest.Builder().Build());

Reunir a solicitação de anúncio

O snippet de código abaixo demonstra como criar um AdLoader que esteja configurado para solicitar anúncios nativos, define delegados para carregamentos de anúncios com êxito e com falha e faz uma solicitação de anúncio.

private void RequestNativeAd() {
    AdLoader adLoader = new AdLoader.Builder(INSERT_AD_UNIT_HERE)
        .ForNativeAd()
        .Build();
    adLoader.OnNativeAdLoaded += this.HandleNativeAdLoaded;
    adLoader.OnAdFailedToLoad += this.HandleAdFailedToLoad;
    adLoader.LoadAd(new AdRequest.Builder().Build());
}

Processar carregamentos de anúncios com falha

O evento OnAdFailedToLoad é do tipo EventHandle<AdFailedToLoadEventArgs>. A análise do motivo de uma falha no carregamento do anúncio desse evento é mostrada abaixo.

private void RequestNativeAd() {
    ...
    adLoader.OnAdFailedToLoad += this.HandleNativeAdFailedToLoad;
}

private void HandleNativeAdFailedToLoad(object sender, AdFailedToLoadEventArgs args) {
    Debug.Log("Native ad failed to load: " + args.Message);
}

Exibir um anúncio nativo

Quando um anúncio nativo é carregado, o evento para o formato de anúncio correspondente é invocado. Dessa forma, seu aplicativo fica responsável por exibir o anúncio, embora não seja necessário fazer isso imediatamente.

Processar o carregamento de anúncios

O evento OnNativeAdLoaded é do tipo EventHandler<NativeAdEventArgs>. O anúncio, encapsulado em um objeto NativeAd, pode ser recuperado de NativeAdEventArgs, conforme mostrado:

private NativeAd nativeAd;
...
private void HandleNativeAdLoaded(object sender, NativeAdEventArgs args) {
    Debug.Log("Native ad loaded.");
    this.nativeAd = args.nativeAd;
}

Recuperar recursos de anúncios nativos

Depois que os anúncios forem carregados, os recursos poderão ser acessados conforme mostrado abaixo. Os recursos gráficos são retornados como objetos Texture2D, e os recursos de texto, como objetos string.

private bool nativeAdLoaded;
private NativeAd nativeAd;

void Update() {
    ...

    if (this.nativeAdLoaded) {
        this.nativeAdLoaded = false;
        // Get Texture2D for the icon asset of native ad.
        Texture2D iconTexture = this.nativeAd.GetIconTexture();

        // Get string for headline asset of native ad.
        string headline = this.nativeAd.GetHeadlineText();
    }
}

private void HandleNativeAdLoaded(object sender, NativeAdEventArgs args) {
    Debug.Log("Native ad loaded.");
    this.nativeAd = args.nativeAd;
    this.nativeAdLoaded = true;
}

Os recursos do anúncio só podem ser acessados na linha de execução principal, por exemplo, do método Update() de um script do Unity. Os recursos abaixo nem sempre estão presentes e precisam ser verificados antes da exibição:

  • GetStarRating()
  • GetStore()
  • GetPrice()
  • GetAdvertiser()
  • GetIconTexture()

Recurso das Opções de anúncios

É necessário exibir o recurso de anúncios de Opções de anúncios como parte do anúncio nativo. Além disso, é importante que o recurso de anúncios de Opções de anúncios seja facilmente visualizado. Escolha cores de plano de fundo e imagens de forma adequada.

Registrar GameObjects para recursos de anúncio

É necessário registrar o GameObject para que o recurso do anúncio seja exibido no seu app do Unity. Se o registro for bem-sucedido, o método usado para registrar o GameObject retornará um bool. Para uma List<GameObject>, o método retorna uma int indicando a contagem de GameObject registrada.

Se o registro de um recurso de anúncio não for concluído, as impressões e os cliques no anúncio nativo correspondente não serão reconhecidos.

if (!this.nativeAd.RegisterIconImageGameObject(icon))
{
    // Handle failure to register the icon ad asset.
}

O GameObject registrado para um recurso de anúncio precisa ter um componente Coliser convexo que represente o tamanho e a forma do GameObject. Se os objetos GameObject registrados para recursos de anúncios não tiverem componentes Collider ou tiverem um configurado incorretamente, os anúncios nativos não funcionarão corretamente.

No snippet de código abaixo, um BoxCollider é adicionado a GameObject, que usa um TextMesh para exibir o recurso de anúncio de título de um anúncio nativo. Depois que o BoxCollider for anexado ao GameObject, ele será dimensionado automaticamente para acomodar o texto do componente TextMesh.

// Create GameObject that will display the headline ad asset.
GameObject headline = new GameObject();
headline.AddComponent<TextMesh>();
headline.GetComponent<TextMesh>().characterSize = 0.5 f;
headline.GetComponent<TextMesh>().anchor = TextAnchor.MiddleCenter;
headline.GetComponent<TextMesh>().color = Color.black;

// Get string of the headline asset.
string headlineText = this.nativeAd.GetHeadlineText();
headline.GetComponent<TextMesh>().text = headlineText;

// Add box collider to the GameObject which will automatically scale.
headline.AddComponent<BoxCollider>();

Demonstração

O código a seguir demonstra como recuperar o recurso de ícone de um anúncio nativo carregado, exibir o recurso de anúncio de ícone definindo a textura de um Quad e registrar o GameObject para usar na exibição. Esse processo de recuperação do recurso de anúncio e o registro dele com a classe de anúncio nativo precisam ser repetidos para cada recurso exibido pelo app.

private GameObject icon;
private bool nativeAdLoaded;
private NativeAd nativeAd;
...
void Update() {
    ...

    if (this.nativeAdLoaded) {
        this.nativeAdLoaded = false;
        // Get Texture2D for icon asset of native ad.
        Texture2D iconTexture = this.nativeAd.GetIconTexture();

        icon = GameObject.CreatePrimitive(PrimitiveType.Quad);
        icon.transform.position = new Vector3(1, 1, 1);
        icon.transform.localScale = new Vector3(1, 1, 1);
        icon.GetComponent<Renderer>().material.mainTexture = iconTexture;

        // Register GameObject that will display icon asset of native ad.
        if (!this.nativeAd.RegisterIconImageGameObject(icon))
        {
            // Handle failure to register ad asset.
        }
    }
}
...

private void HandleNativeAdLoaded(object sender, NativeAdEventArgs args) {
    Debug.Log("Native ad loaded.");
    this.nativeAd = args.nativeAd;
    this.nativeAdLoaded = true;
}