Formatos de anúncios nativos personalizados

Formatos de anúncios nativos personalizados

Além dos formatos nativos definidos pelo sistema, os editores do Ad Manager têm a opção de criar os próprios formatos de anúncios nativos definindo listas personalizadas de recursos. Eles são chamados de formatos de anúncio nativo personalizado e podem ser usados com anúncios reservados. Isso permite que os editores transmitam dados estruturados arbitrários para os apps. 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.

Criar um AdLoader

Assim como os anúncios nativos, os formatos de anúncios nativos personalizados são carregados usando a classe AdLoader:

Java

AdLoader adLoader = new AdLoader.Builder(context, "/21775744923/example/native")
    .forCustomFormatAd("10063170",
      new NativeCustomFormatAd.OnCustomFormatAdLoadedListener() {
          @Override
          public void onCustomFormatAdLoaded(NativeCustomFormatAd ad) {
              // Show the custom format and record an impression.
          }
      },
      new NativeCustomFormatAd.OnCustomClickListener() {
          @Override
          public void onCustomClick(NativeCustomFormatAd ad, String s) {
              // Handle the click action
          }
      })
    .withAdListener( ... )
    .withNativeAdOptions( ... )
    .build();

Kotlin

val adLoader = AdLoader.Builder(this, "/21775744923/example/native")
        .forCustomFormatAd("10063170",
            { ad ->
                // Show the custom format and record an impression.
            },
            { ad, s ->
            // Handle the click action
            })
        .withAdListener( ... )
        .withNativeAdOptions( ... )
        .build()

O método forCustomFormatAd configura o AdLoader para solicitar formatos de anúncios nativos personalizados. Há três parâmetros transmitidos para o método:

• O ID do formato de anúncio nativo personalizado que o AdLoader precisa solicitar. Cada formato de anúncio nativo personalizado tem um ID associado. Esse parâmetro indica qual formato o app quer que a AdLoader solicite.
• Um OnCustomFormatAdLoadedListener para ser invocado quando um anúncio for carregado.
• Um OnCustomClickListener opcional para ser invocado quando o usuário tocar ou clicar no anúncio. Para saber mais sobre esse listener, consulte a seção "Como processar cliques e impressões" abaixo.

Como um único bloco de anúncios pode ser configurado para veicular mais de um formato de criativo, forCustomFormatAd pode ser chamado várias vezes com IDs de formato exclusivos para preparar o carregador de anúncios para mais de um possível formato de anúncio nativo personalizado.

Observação: forNativeAd e forCustomFormatAd podem ser usados simultaneamente com um único AdLoader se você tiver um bloco de anúncios configurado para veicular vários formatos de anúncio.

ID do formato de anúncio nativo personalizado

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

Cada ID do formato de anúncio nativo personalizado aparece ao lado do nome. Clicar em um dos nomes leva você a uma tela de detalhes mostrando informações sobre os campos do formato:

Nela, é possível adicionar, editar e remover campos individuais. Anote o Nome de cada um dos recursos. O nome é a chave usada para receber os dados de cada recurso ao exibir o formato de anúncio nativo personalizado.

Mostrar formatos de anúncios nativos personalizados

Os formatos de anúncios nativos personalizados são diferentes dos definidos pelo sistema porque os editores podem definir a própria lista de recursos que compõem um anúncio. Portanto, o processo de exibição de um deles difere dos formatos definidos pelo sistema de algumas maneiras:

1. Como a classe NativeCustomFormatAd é destinada a processar qualquer um dos formatos de anúncios nativos personalizados que você define no Ad Manager, ela não tem "getters" nomeados para recursos. Em vez disso, ele oferece métodos como getText e getImage, que usam o nome do campo como parâmetro.
2. Não há uma classe de visualização de anúncio dedicada, como NativeAdView, para usar com NativeCustomFormatAd. Você pode usar qualquer layout que faça sentido para a experiência do usuário.
3. Como não há uma classe ViewGroup dedicada, não é necessário registrar nenhuma das visualizações usadas para mostrar os recursos do anúncio. Isso economiza algumas linhas de código ao exibir o anúncio, mas também significa que você precisará fazer um pouco mais de trabalho para processar os cliques mais tarde.

Confira um exemplo de função que mostra um NativeCustomFormatAd:

Java

public void displayCustomFormatAd (ViewGroup parent,
                                     NativeCustomFormatAd customFormatAd) {
    // Inflate a layout and add it to the parent ViewGroup.
    LayoutInflater inflater = (LayoutInflater) parent.getContext()
            .getSystemService(Context.LAYOUT_INFLATER_SERVICE);
    View adView = inflater.inflate(R.layout.custom_format_ad, parent);

    // Locate the TextView that will hold the value for "Headline" and
    // set its text.
    TextView myHeadlineView = (TextView) adView.findViewById(R.id.headline);
    myHeadlineView.setText(customFormatAd.getText("Headline"));

    // Locate the ImageView that will hold the value for "MainImage" and
    // set its drawable.
    Button myMainImageView = (ImageView) adView.findViewById(R.id.main_image);
    myMainImageView.setImageDrawable(
            customFormatAd.getImage("MainImage").getDrawable());

    ...
    // Continue locating views and displaying assets until finished.
    ...
}

Kotlin

public fun displayCustomFormatAd (parent: ViewGroup,
                                customFormatAd: NativeCustomFormatAd) {
    val adView = layoutInflater
            .inflate(R.layout.ad_simple_custom_format, null)

    val myHeadlineView = adView.findViewById<TextView>(R.id.headline)
    myHeadlineView.setText(customFormatAd.getText("Headline"));

    // Locate the ImageView that will hold the value for "MainImage" and
    // set its drawable.
    val myMainImageView = adView.findViewById(R.id.main_image);
    myMainImageView.setImageDrawable(
            customFormatAd.getImage("MainImage").drawable);

    ...
    // Continue locating views and displaying assets until finished.
    ...
}

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 "Sobre este anúncio" do Google. Ao implementar anúncios nativos personalizados, você é responsável por renderizar o ícone "Opções de anúncios". Recomendamos que você siga algumas etapas para renderizar e definir o listener de cliques do ícone "Opções de anúncios" ao renderizar os principais recursos de anúncios.

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

Importante: defina o ícone da Opções de anúncios com pelo menos 15 x 15 pixels.

<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 da AdChoices e configuram o comportamento de clique apropriado.

Java

private AdSimpleCustomTemplateBinding customTemplateBinding;

private void populateAdView(final NativeCustomFormatAd nativeCustomFormatAd) {
  // Render the AdChoices icon.
  String adChoicesKey = NativeAdAssetNames.ASSET_ADCHOICES_CONTAINER_VIEW;
  NativeAd.Image adChoicesAsset = nativeCustomFormatAd.getImage(adChoicesKey);
  if (adChoicesAsset == null) {
    customTemplateBinding.adChoices.setVisibility(View.GONE);
  } else {
    customTemplateBinding.adChoices.setVisibility(View.VISIBLE);
    customTemplateBinding.adChoices.setImageDrawable(adChoicesAsset.getDrawable());

    // Enable clicks on AdChoices.
    customTemplateBinding.adChoices.setOnClickListener(
        new View.OnClickListener() {
          @Override
          public void onClick(View v) {
            nativeCustomFormatAd.performClick(adChoicesKey);
          }
        });
  }
  ...
}

Kotlin

private lateinit var customTemplateBinding: AdSimpleCustomTemplateBinding

private fun populateAdView(nativeCustomFormatAd: NativeCustomFormatAd) {
  // Render the AdChoices icon.
  val adChoicesKey = NativeAdAssetNames.ASSET_ADCHOICES_CONTAINER_VIEW
  val adChoicesAsset = nativeCustomFormatAd.getImage(adChoicesKey)
  if (adChoicesAsset == null) {
    customTemplateBinding.adChoices.visibility = View.GONE
  } else {
    customTemplateBinding.adChoices.setImageDrawable(adChoicesAsset.drawable)
    customTemplateBinding.adChoices.visibility = View.VISIBLE

    // Enable clicks on AdChoices.
    customTemplateBinding.adChoices.setOnClickListener {
      nativeCustomFormatAd.performClick(adChoicesKey)
    }
  }
  ...
}

Importante: se você usar o controle de download de imagens para solicitar apenas URLs de imagens, o recurso AdChoices vai respeitar essa configuração e retornará apenas o URL da imagem.

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

Ao criar um formato personalizado, você tem a opção de tornar o formato qualificado para vídeo.

Na implementação do app, você pode usar NativeCustomFormatAd.getMediaContent() para acessar o conteúdo de mídia. Em seguida, chame setMediaContent() para definir o conteúdo de mídia na visualização de mídia. Se o anúncio não tiver conteúdo de vídeo, faça planos alternativos para mostrar o anúncio sem um vídeo.

Observação: ao contrário dos anúncios nativos, que contêm uma imagem na visualização de mídia quando o vídeo não está disponível, a visualização de mídia de um anúncio nativo personalizado não tem conteúdo se não tiver vídeo.

O exemplo abaixo verifica se o anúncio tem conteúdo em vídeo e exibe uma imagem no lugar dele se um vídeo não estiver disponível:

Java

// Called when a custom native ad loads.
@Override
public void onCustomFormatAdLoaded(final NativeCustomFormatAd ad) {

  MediaContent mediaContent = ad.getMediaContent();

  // Assumes you have a FrameLayout in your view hierarchy with the id media_placeholder.
  FrameLayout mediaPlaceholder = (FrameLayout) findViewById(R.id.media_placeholder);

  // Apps can check the MediaContent's hasVideoContent property to determine if the
  // NativeCustomFormatAd has a video asset.
  if (mediaContent != null && mediaContent.hasVideoContent()) {
    MediaView mediaView = new MediaView(mediaPlaceholder.getContext());
    mediaView.setMediaContent(mediaContent);
    mediaPlaceholder.addView(mediaView);

    // Create a new VideoLifecycleCallbacks object and pass it to the VideoController. The
    // VideoController will call methods on this object when events occur in the video
    // lifecycle.
    VideoController vc = mediaContent.getVideoController();
    vc.setVideoLifecycleCallbacks(
        new VideoController.VideoLifecycleCallbacks() {
          @Override
          public void onVideoEnd() {
            // Publishers should allow native ads to complete video playback before
            // refreshing or replacing them with another ad in the same UI location.
            super.onVideoEnd();
          }
        });
  } else {
    ImageView mainImage = new ImageView(this);
    mainImage.setAdjustViewBounds(true);
    mainImage.setImageDrawable(ad.getImage("MainImage").getDrawable());
    mediaPlaceholder.addView(mainImage);
    mainImage.setOnClickListener(
        new View.OnClickListener() {
          @Override
          public void onClick(View view) {
            ad.performClick("MainImage");
          }
        });
  }
}

Kotlin

// Called when a custom native ad loads.
NativeCustomFormatAd.OnCustomFormatAdLoadedListener { ad ->

  val mediaContent = ad.mediaContent

  // Apps can check the MediaContent's hasVideoContent property to determine if the
  // NativeCustomFormatAd has a video asset.
  if (mediaContent != null && mediaContent.hasVideoContent()) {
    val mediaView = MediaView(mediaPlaceholder.getContest())
    mediaView.mediaContent = mediaContent

    val videoController = mediaContent.videoController

    // Create a new VideoLifecycleCallbacks object and pass it to the VideoController. The
    // VideoController will call methods on this object when events occur in the video
    // lifecycle.
    if (videoController != null) {
      videoController.videoLifecycleCallbacks =
        object : VideoController.VideoLifecycleCallbacks() {
          override fun onVideoEnd() {
            // Publishers should allow native ads to complete video playback before refreshing
            // or replacing them with another ad in the same UI location.
            super.onVideoEnd()
          }
        }
    }
  } else {
    val mainImage = ImageView(this)
    mainImage.adjustViewBounds = true
    mainImage.setImageDrawable(ad.getImage("MainImage")?.drawable)

    mainImage.setOnClickListener { ad.performClick("MainImage") }
    customTemplateBinding.simplecustomMediaPlaceholder.addView(mainImage)
  }
}

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

Faça o download do exemplo de renderização personalizada do Ad Manager para conferir um exemplo de vídeo nativo em ação.

Cliques e impressões do formato de anúncio nativo personalizado

Com formatos de anúncio nativo personalizados, seu app é responsável por registrar impressões e informar eventos de clique ao SDK dos anúncios para dispositivos móveis do Google.

Impressões de registro

Para registrar uma impressão de um anúncio de formato personalizado, chame o método recordImpression no NativeCustomFormatAd correspondente:

myCustomFormatAd.recordImpression();

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

Informar cliques

Para informar ao SDK que um clique ocorreu em uma visualização de recurso, chame o método performClick no NativeCustomFormatAd correspondente e transmita o nome do recurso em que foi clicado. Por exemplo, se você tivesse um recurso no seu formato personalizado chamado "MainImage" e quisesse informar um clique no ImageView correspondente a esse recurso, seu código ficaria assim:

myCustomFormatAd.performClick("MainImage");

Não é necessário chamar esse método para todas as visualizações associadas ao seu anúncio. Se você tivesse outro campo chamado "Caption" que deveria 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 clique é realizado em um anúncio de formato personalizado, há três respostas possíveis do SDK, tentadas nesta ordem:

1. Invocar o OnCustomClickListener de AdLoader, se ele tiver sido fornecido.
2. Para cada um dos URLs de link direto do anúncio, tente localizar um solucionador de conteúdo e iniciar o primeiro que for resolvido.
3. Abra um navegador e navegue até o URL de destino tradicional do anúncio.

O método forCustomFormatAd aceita um OnCustomClickListener. Se você transmitir um objeto de listener, o SDK vai invocar o método onCustomClick e não realizar nenhuma outra ação. No entanto, se você transmitir um valor nulo como o listener, o SDK vai voltar para os URLs de destino e/ou de link direto registrados com o anúncio.

Os listeners de cliques personalizados permitem que o app decida a melhor ação a ser tomada em resposta a um clique, seja a atualização da interface, o lançamento de uma nova atividade ou apenas o registro do clique. Confira um exemplo que simplesmente registra que um clique ocorreu:

Java

AdLoader adLoader = new AdLoader.Builder(context, "/21775744923/example/native")
    .forCustomFormatAd("10063170",
      new NativeCustomFormatAd.OnCustomFormatAdLoadedListener() {
        // Display the ad.
      },
      new NativeCustomFormatAd.OnCustomClickListener() {
          @Override
          public void onCustomClick(NativeCustomFormatAd ad, String assetName) {
            Log.i("MyApp", "A custom click just happened for " + assetName + "!");
          }
      }).build();

Kotlin

val adLoader = AdLoader.Builder(this, "/21775744923/example/native")
    .forCustomFormatAd("10063170",
        { ad ->
            // Display the ad.
        },
        { ad, assetName ->
                Log.i("MyApp", "A custom click just happened for $assetName!")
    }).build()

Pode parecer estranho que listeners de cliques personalizados existam. Afinal, seu app acabou de informar ao SDK que um clique ocorreu. Por que o SDK precisaria informar isso ao app?

Esse fluxo de informações é útil por alguns motivos, mas o mais importante é que ele permite que o SDK continue no controle da resposta ao clique. Ele pode fazer ping automaticamente em URLs de rastreamento de terceiros que foram definidos para o criativo, por exemplo, e processar outras tarefas em segundo plano, sem nenhum código extra.