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úncios nativos personalizados 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, "/6499/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, "/6499/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 a AdLoader para solicitar formatos de anúncio nativo personalizados. Há três parâmetros transmitidos ao método:

• O ID do formato de anúncio nativo personalizado que o AdLoader deve solicitar. Cada formato de anúncio nativo personalizado tem um ID associado a ele. Esse parâmetro indica qual formato seu app quer que o AdLoader solicite.
• Um OnCustomFormatAdLoadedListener a ser invocado quando um anúncio é carregado.
• Um OnCustomClickListener opcional a ser invocado quando o usuário toca ou clica 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 a fim de preparar o carregador de anúncios para mais de um formato de anúncio nativo personalizado possível.

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 do anúncio nativo personalizado

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

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

Aqui, campos individuais podem ser adicionados, editados e removidos. Anote o Nome de cada um dos recursos. O nome é a chave usada para coletar os dados de cada recurso ao exibir o formato de anúncio nativo personalizado.

Formatos de anúncios nativos personalizados de display

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

1. Como a classe NativeCustomFormatAd precisa processar qualquer um dos formatos de anúncios nativos personalizados definidos no Ad Manager, ela não tem getters para os recursos. Em vez disso, ela 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 sua 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ê vai precisar fazer um pouco mais de trabalho para processar os cliques mais tarde.

Confira um exemplo de função que exibe 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.
    ...
}

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

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

Na implementação do app, use 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 mostrá-lo sem vídeo.

Observação :diferentemente 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 vai ter conteúdo se não tiver vídeo.

O exemplo abaixo verifica se o anúncio tem conteúdo de 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 um exemplo funcional de vídeo nativo em ação.

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

Com formatos de anúncios nativos personalizados, o aplicativo registra as impressões e informa os eventos de clique ao SDK dos anúncios para dispositivos móveis do Google.

Registrar impressões

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 duas vezes para o mesmo anúncio acidentalmente, o SDK vai impedir automaticamente que impressões duplicadas sejam registradas 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 que foi clicado. Por exemplo, se você tivesse um recurso no seu formato personalizado chamado "MainImage" e quisesse informar um clique no ImageView que correspondesse 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 estar 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, que podem ser tentadas nesta ordem:

1. Invoque o OnCustomClickListener de AdLoader, se um tiver sido fornecido.
2. Para cada um dos URLs de link direto do anúncio, tente localizar um resolvedor de conteúdo e iniciar o primeiro que for resolvido.
3. Abra um navegador e acesse 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á outras ações. No entanto, se você transmitir um valor nulo como listener, o SDK vai recorrer aos URLs de destino e/ou 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 atualizar a IU, iniciar uma nova atividade ou apenas registrar o clique. Veja um exemplo que simplesmente registra que um clique ocorreu:

Java

AdLoader adLoader = new AdLoader.Builder(context, "/6499/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, "/6499/example/native")
    .forCustomFormatAd("10063170",
        { ad ->
            // Display the ad.
        },
        { ad, assetName ->
                Log.i("MyApp", "A custom click just happened for $assetName!")
    }).build()

A princípio, a existência de listeners de cliques personalizados pode parecer estranha. Afinal, seu app acabou de informar ao SDK que ocorreu um clique. Então, por que o SDK deveria informar isso ao app?

Esse fluxo de informações é útil por alguns motivos, mas, mais importante, permite que o SDK permaneça no controle da resposta ao clique. Ele pode dar um ping automaticamente em URLs de rastreamento de terceiros que foram definidos para o criativo, por exemplo, e realizar outras tarefas em segundo plano, sem precisar de outro código.