Formatos de anúncios nativos personalizados

Além dos formatos nativos definidos pelo sistema, os publishers do Ad Manager têm a opção de criar os próprios formatos de anúncios nativos definindo listas de recursos personalizadas. Eles são conhecidos como formatos de anúncios nativos personalizados e podem ser usados com anúncios de reserva. Com isso, publishers conseguem passar dados estruturados arbitrários para os apps deles. Esses anúncios são representados pelo objeto NativeCustomFormatAd.

Carregar formatos de anúncios nativos personalizados

Este guia explica como carregar e exibir formatos de anúncios nativos personalizados.

Carregar um anúncio nativo personalizado

Para carregar um anúncio nativo personalizado, faça o seguinte:

  1. Inclua o tipo NativeAdType.CUSTOM_NATIVE como um tipo de anúncio no NativeAdRequest.

  2. Defina o ID do formato do anúncio nativo personalizado.

Kotlin

val adRequest =
  NativeAdRequest.Builder("AD_UNIT_ID", listOf(NativeAdType.CUSTOM_NATIVE))
    .setCustomFormatIds(listOf("CUSTOM_NATIVE_FORMAT_ID"))
    .build()

// Load the native ad with the ad request and callback.
NativeAdLoader.load(
  adRequest,
  object : NativeAdLoaderCallback {
    override fun onCustomNativeAdLoaded(customNativeAd: CustomNativeAd) {
      // TODO: Store the custom native ad.
    }

    override fun onAdFailedToLoad(adError: LoadAdError) {}
  },
)

Java

NativeAdRequest adRequest =
    new NativeAdRequest.Builder("AD_UNIT_ID", List.of(NativeAd.NativeAdType.CUSTOM_NATIVE))
        .setCustomFormatIds(Arrays.asList("CUSTOM_NATIVE_FORMAT_ID"))
        .build();

// Load the native ad with the ad request and callback.
NativeAdLoader.load(
    adRequest,
    new NativeAdLoaderCallback() {
      @Override
      public void onCustomNativeAdLoaded(@NonNull CustomNativeAd customNativeAd) {
        // TODO: Store the custom native ad.
      }

      @Override
      public void onAdFailedToLoad(@NonNull LoadAdError adError) {}
    });

ID do formato de anúncio nativo personalizado

O ID usado para identificar um formato de anúncio nativo personalizado pode ser encontrado na interface do Ad Manager, na seção Nativo do menu suspenso Exibição:

O ID do formato de cada anúncio nativo personalizado aparece ao lado do nome. Quando você clica em um dos nomes, é exibida uma tela com informações sobre os campos do formato:

Nessa tela, é possível adicionar, editar e remover campos individuais. Confira o Nome de cada um dos recursos. Ele é a chave usada para receber os dados de cada um deles ao exibir seu formato de anúncio nativo personalizado.

Exibir formatos de anúncios nativos personalizados

Esses formatos diferem dos definidos pelo sistema porque os publishers podem especificar a própria lista de recursos que compõem um anúncio. Dessa forma, o processo de exibir um modelo personalizado se diferencia dos formatos definidos pelo sistema de alguns modos:

  1. Os recursos de texto e imagem estão disponíveis com os getters getText() e getImage(), que usam o nome do campo como parâmetro.
  2. Como não há uma classe ViewGroup dedicada para registrar no Google, você precisa registrar impressões e cliques manualmente.
  3. Um anúncio nativo personalizado terá um conteúdo de mídia null se não tiver um recurso de vídeo.

Este exemplo mostra como exibir um CustomNativeAd:

Kotlin

private fun displayCustomNativeAd(customNativeAd: CustomNativeAd, context: Context) {
  // Render the text elements.

  // The `customNativeAdBinding` is the layout binding for the ad container that
  // contains all `CustomNativeAd` assets.
  customNativeAdBinding.headline.text = customNativeAd.getText("Headline")
  customNativeAdBinding.caption.text = customNativeAd.getText("Caption")

  // If the main asset is an image, render it with an ImageView.
  val imageView = ImageView(context)
  imageView.adjustViewBounds = true
  imageView.setImageDrawable(customNativeAd.getImage("MainImage")?.drawable)
  imageView.setOnClickListener { customNativeAd.performClick("MainImage") }
  customNativeAdBinding.mediaPlaceholder.addView(imageView)

  // Render the ad choices icon.
  renderAdChoices(customNativeAd)

  // Record an impression.
  customNativeAd.recordImpression()
}

Java

private void displayCustomNativeAd(CustomNativeAd customNativeAd, Context context) {
  // Render the text elements.

  // The `customNativeAdBinding` is the layout binding for the ad container that
  // contains all `CustomNativeAd` assets.
  if (customNativeAdBinding != null) {
    customNativeAdBinding.headline.setText(customNativeAd.getText("Headline"));
    customNativeAdBinding.caption.setText(customNativeAd.getText("Caption"));

    ImageView imageView = new ImageView(context);
    imageView.setAdjustViewBounds(true);
    imageView.setImageDrawable(customNativeAd.getImage("MainImage").getDrawable());
    imageView.setOnClickListener(
        new View.OnClickListener() {
          @Override
          public void onClick(View v) {
            customNativeAd.performClick("MainImage");
          }
        });
    customNativeAdBinding.mediaPlaceholder.addView(imageView);

    // Render the ad choices icon.
    renderAdChoices(customNativeAd);

    // Record an impression.
    customNativeAd.recordImpression();
  }
}

Vídeo nativo para formatos de anúncios nativos personalizados

Ao criar um formato personalizado, você pode torná-lo qualificado para vídeo.

Na implementação do app, use CustomNativeAd.getMediaContent() para receber o conteúdo de mídia. Em seguida, chame setMediaContent() para definir esse conteúdo na sua visualização de mídia. Se o anúncio tiver conteúdo de mídia null, faça planos alternativos para veicular a publicidade sem vídeo.

O exemplo abaixo verifica se o anúncio tem conteúdo de vídeo e mostra uma imagem no lugar dele se esse não for o caso:

Kotlin

private fun displayVideoCustomNativeAd(customNativeAd: CustomNativeAd, context: Context) {
  // Check whether the custom native ad has video content.
  val mediaContent = customNativeAd.mediaContent
  if (mediaContent != null && mediaContent.hasVideoContent) {
    // Render the media content in a MediaView.
    val mediaView = MediaView(context)
    mediaView.mediaContent = mediaContent
    customNativeAdBinding.mediaPlaceholder.addView(mediaView)
  } else {
    // Fall back to other assets defined on your custom native ad.
    val imageView = ImageView(context)
    imageView.adjustViewBounds = true
    imageView.setImageDrawable(customNativeAd.getImage("MainImage")?.drawable)
    customNativeAdBinding.mediaPlaceholder.addView(imageView)
  }

  // Record an impression.
  customNativeAd.recordImpression()
}

Java

private void displayVideoCustomNativeAd(CustomNativeAd customNativeAd, Context context) {
  // Check whether the custom native ad has video content.
  MediaContent mediaContent = customNativeAd.getMediaContent();
  if (mediaContent != null && mediaContent.getHasVideoContent()) {
    // Render the media content in a MediaView.
    MediaView mediaView = new MediaView(context);
    mediaView.setMediaContent(mediaContent);
    customNativeAdBinding.mediaPlaceholder.addView(mediaView);
  } else {
    // Fall back to other assets defined on your custom native ad.
    ImageView imageView = new ImageView(context);
    imageView.setAdjustViewBounds(true);
    imageView.setImageDrawable(customNativeAd.getImage("MainImage").getDrawable());
    customNativeAdBinding.mediaPlaceholder.addView(imageView);
  }

  // Record an impression.
  customNativeAd.recordImpression();
}

Consulte Anúncios em vídeo para mais informações sobre como personalizar a experiência de vídeo de um anúncio nativo personalizado.

Renderizar o ícone "Opções de anúncios"

Como parte do apoio à Lei dos Serviços Digitais (DSA), os anúncios de reserva veiculados no Espaço Econômico Europeu (EEE) exigem um ícone Opções de Anúncios e um link para a página do Google Sobre este anúncio. Ao implementar anúncios nativos personalizados, você é responsável por renderizar esse ícone. Ao gerar os principais recursos do seu anúncio, você também precisa seguir estas etapas para renderizar o ícone Opções de Anúncios e definir o listener de cliques dele.

O exemplo a seguir pressupõe que você definiu um elemento <ImageView /> na hierarquia de visualização para armazenar esse logotipo.

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android">
    <ImageView
        android:id="@+id/adChoices"
        android:layout_width="15dp"
        android:layout_height="15dp"
        android:adjustViewBounds="true"
        android:contentDescription="AdChoices icon." />
</LinearLayout>

Os exemplos a seguir renderizam o ícone e configuram o comportamento de clique adequado.

Kotlin

private fun renderAdChoices(customNativeAd: CustomNativeAd) {
  // Render the AdChoices image.
  val adChoiceAsset = customNativeAd.getImage(NativeAdAssetNames.ASSET_ADCHOICES_CONTAINER_VIEW)
  if (adChoiceAsset != null) {
    customNativeAdBinding.adchoices.setImageDrawable(adChoiceAsset.drawable)
    customNativeAdBinding.adchoices.visibility = View.VISIBLE
    customNativeAdBinding.adchoices.setOnClickListener {
      // Handle click. See the next section for more details.
      customNativeAd.performClick(NativeAdAssetNames.ASSET_ADCHOICES_CONTAINER_VIEW)
    }
  } else {
    customNativeAdBinding.adchoices.visibility = View.GONE
  }
}

Java

private void renderAdChoices(CustomNativeAd customNativeAd) {
  // Render the AdChoices image.
  Image adChoiceAsset =
      customNativeAd.getImage(NativeAdAssetNames.ASSET_ADCHOICES_CONTAINER_VIEW);
  if (adChoiceAsset != null) {
    if (customNativeAdBinding != null) {
      customNativeAdBinding.adchoices.setImageDrawable(adChoiceAsset.getDrawable());
      customNativeAdBinding.adchoices.setVisibility(View.VISIBLE);
      customNativeAdBinding.adchoices.setOnClickListener(
          new View.OnClickListener() {
            @Override
            public void onClick(View v) {
              // Handle click.
              customNativeAd.performClick(NativeAdAssetNames.ASSET_ADCHOICES_CONTAINER_VIEW);
            }
          });
    }
  } else {
    if (customNativeAdBinding != null) {
      customNativeAdBinding.adchoices.setVisibility(View.GONE);
    }
  }
}

Registrar impressões e gerar relatórios de cliques

Seu app é responsável por registrar impressões e informar eventos de cliques ao SDK dos Anúncios para Dispositivos Móveis do Google (beta).

Registrar impressões

Para registrar impressões de um anúncio nativo personalizado, chame o método recordImpression() do anúncio:

Kotlin

// Record an impression.
customNativeAd.recordImpression()

Java

// Record an impression.
customNativeAd.recordImpression();

Se o app chamar o método duas vezes para o mesmo anúncio por engano, o SDK vai automaticamente impedir que uma impressão duplicada seja registrada para uma única solicitação.

Gerar relatórios de cliques

Para informar ao SDK que uma visualização de recurso recebeu um clique, chame o método performClick() do anúncio. Forneça o nome do recurso que foi clicado usando a mesma string definida na interface do Ad Manager.

Kotlin

imageView.setOnClickListener { customNativeAd.performClick("MainImage") }

Java

imageView.setOnClickListener(
    new View.OnClickListener() {
      @Override
      public void onClick(View v) {
        customNativeAd.performClick("MainImage");
      }
    });

Não é necessário chamar esse método para cada visualização associada ao seu anúncio. Se você tivesse outro campo chamado "Caption" projetado para ser exibido, mas não clicado ou tocado pelo usuário, seu app não precisaria chamar performClick para a visualização desse recurso.

Responder a ações de clique personalizadas

Quando um anúncio de formato personalizado recebe um clique, existem três respostas possíveis do SDK, que são executadas nesta ordem:

  1. Invocar OnCustomClickListener, se um tiver sido fornecido.
  2. Tentar localizar um resolvedor de conteúdo para cada um dos URLs de links diretos do anúncio e iniciar o primeiro que conseguir resolver.
  3. Abra um navegador e acesse o URL de destino do anúncio.

Para implementar uma ação de clique personalizada, forneça um OnCustomClickListener:

Kotlin

customNativeAd.onCustomClickListener =
  object : OnCustomClickListener {
    override fun onCustomClick(assetName: String) {
      // Perform your custom action.
    }
  }

Java

customNativeAd.setOnCustomClickListener(
    new OnCustomClickListener() {
      @Override
      public void onCustomClick(@NonNull String assetName) {
        // Perform your custom action.
      }
    });

A princípio, a própria existência de listeners de cliques em anúncios personalizados parece estranha. Afinal de contas, seu app acabou de informar ao SDK que houve um clique. Por que o SDK deveria dizer o mesmo para o app?

Essa troca de informações é útil por alguns motivos, mas principalmente porque assim o SDK permanece no controle da resposta ao clique. Ele pode dar um ping automaticamente em URLs de rastreamento de terceiros que tenham sido configurados para o criativo, por exemplo, e executar outras tarefas nos bastidores sem códigos adicionais.