Native Ads – Custom Rendering

No momento, esse recurso é oferecido como uma versão Beta limitada. Se você tiver interesse em testá-la, converse sobre essa possibilidade com seu gerente da conta. Esse recurso será disponibilizado a todos os editores após a conclusão da versão Beta.

Consulte o laboratório de códigos para ver instruções detalhadas da implementação da renderização personalizada nativa.

Este guia explica como usar o SDK de anúncios para dispositivos móveis do Google com a finalidade de implementar anúncios nativos do DFP em um aplicativo Android, além de outros aspectos importantes a serem considerados durante esse processo.

Pré-requisitos

Este guia parte da premissa de que você tem um conhecimento razoável sobre o funcionamento do SDK de anúncios para dispositivos móveis do Google. Se não for o caso, considere a possibilidade de consultar nosso Guia de primeiros passos.

O que é um anúncio nativo?

Os anúncios nativos são um tipo de publicidade exibida aos usuários por meio de componentes da IU que são nativos à plataforma. Eles são exibidos com base nos mesmos tipos de visualização que você usa para criar seus layouts. Além disso, esses anúncios podem ser formatados de modo compatível com o design visual da experiência do usuário na qual são exibidos. Com relação à codificação, isso significa que seu aplicativo recebe um objeto NativeAd que contém os recursos do anúncio nativo que é carregado. Dessa forma, o aplicativo (não o SDK) é responsável por exibir esses recursos.

Formatos de anúncios nativos definidos pelo sistema

Existem dois formatos de anúncios nativos definidos pelo sistema: instalação do app e conteúdo. Os anúncios de instalação do app são representados por NativeAppInstallAd, enquanto os anúncios de conteúdo, por NativeContentAd. Esses objetos contêm os recursos do anúncio nativo.

Formatos de anúncios nativos personalizados

Além dos formatos nativos definidos pelo sistema, os editores do DFP têm a opção de criar seus próprios formatos de anúncios personalizados por meio da definição de listas de recursos padronizadas. Eles são conhecidos como formatos de anúncios nativos personalizados e podem ser usados com anúncios reservados. Isso permite que os editores passem dados estruturados arbitrários para os aplicativos deles. Esses anúncios são representados pelo objeto NativeCustomTemplateAd.

Como carregar formatos de anúncios definidos pelo sistema

Os anúncios nativos são carregados por meio da classe AdLoader, que tem sua própria classe Builder para personalizá-la durante a criação. Com a adição de listeners ao AdLoader durante a criação dele, um aplicativo especifica quais tipos de anúncio nativo ele poderá receber. Dessa forma, o AdLoader passa a solicitar apenas esses tipos.

Como criar um AdLoader

O código a seguir mostra como criar um AdLoader que possa carregar um anúncio de instalação do app ou de conteúdo em uma única solicitação:

AdLoader adLoader = new AdLoader.Builder(context, "/6499/example/native")
    .forAppInstallAd(new OnAppInstallAdLoadedListener() {
        @Override
        public void onAppInstallAdLoaded(NativeAppInstallAd appInstallAd) {
            // Show the app install ad.
        }
    })
    .forContentAd(new OnContentAdLoadedListener() {
        @Override
        public void onContentAdLoaded(NativeContentAd contentAd) {
            // Show the content ad.
        }
    })
    .withAdListener(new AdListener() {
        @Override
        public void onAdFailedToLoad(int errorCode) {
            // Handle the failure by logging, altering the UI, etc.
        }
    })
    .withNativeAdOptions(new NativeAdOptions.Builder()
            // Methods in the NativeAdOptions.Builder class can be
            // used here to specify individual options settings.
            .build())
    .build();

Preparação para os formatos individuais

Os primeiros métodos acima são responsáveis por preparar o AdLoader para um tipo específico de anúncio nativo:

forAppInstallAd: a chamada desse método configura o AdLoader para solicitar anúncios de instalação do app. Quando um anúncio é carregado corretamente, o método onAppInstallAdLoaded do objeto do listener é chamado.

forContentAd: esse método funciona da mesma forma que forAppInstallAd, porém, com anúncios de conteúdo. Quando um anúncio é carregado corretamente, o método onContentAdLoaded é invocado no objeto do listener.

Mesmo quando o carregador de anúncios tiver gerenciadores de vários formatos de anúncios nativos, o SDK fará somente uma solicitação de anúncio. O Google seleciona e retorna o anúncio que maximiza o rendimento do editor.

Como usar AdListener com um AdLoader

Durante a criação do AdLoader acima, é incluída uma função para definir um AdListener: withAdListener. Essa é uma etapa opcional. O método recebe um AdListener como um parâmetro único, que recebe retornos de chamadas do AdLoader quando ocorrem eventos de ciclo de vida do anúncio:

.withAdListener(new AdListener() {
  // AdListener callbacks like OnAdFailedToLoad, OnAdOpened, and so on,
  // can be overridden here.
})

Há uma diferença importante entre o modo como AdListeners funciona com anúncios nativos, banners e intersticiais. Como o AdLoader tem listeners próprios específicos de cada formato (OnAppInstallAdLoadedListener e assim por diante) para usar quando um anúncio é carregado, o método onAdLoaded do AdListener não é chamado quando um anúncio nativo é carregado.

NativeAdOptions

A última função incluída na criação do AdLoader acima é outro método opcional, withNativeAdOptions:

.withNativeAdOptions(new NativeAdOptions.Builder()
        // Methods in the NativeAdOptions.Builder class can be
        // used here to specify individual options settings.
        .build()
)

O objeto NativeAdOptions permite que os aplicativos definam opções específicas usadas na criação da solicitação. A classe Builder oferece esses métodos para uso na criação de uma instância:

setReturnUrlsForImageAssets: os recursos de imagem dos anúncios nativos são retornados por meio de instâncias do NativeAd.Image, que contém um Drawable e um Uri. Se essa opção estiver definida como "false" (que é a configuração padrão), o SDK buscará recursos de imagem automaticamente e preencherá o Drawable e o Uri para você. No entanto, se essa opção estiver definida como "true", o SDK preencherá somente o campo Uri, permitindo que você faça o download das imagens reais de acordo com as suas necessidades.

setImageOrientation: alguns criativos têm várias imagens disponíveis que correspondem a diferentes orientações do dispositivo. A chamada desse método com umas das constantes de orientação de NativeAdOptions (ORIENTATION_PORTRAIT, ORIENTATION_LANDSCAPE ou ORIENTATION_ANY) solicita imagens de uma orientação específica. Se esse método não for chamado, o valor padrão de ORIENTATION_ANY será usado.

Se você usar setImageOrientation para especificar sua preferência pela orientação de imagem como retrato ou paisagem, primeiro o SDK colocará as imagens compatíveis com essa orientação nas matrizes de recursos de imagens e, em seguida, as imagens não compatíveis com essa orientação. Como alguns anúncios estão disponíveis em somente uma orientação, é importante que os editores configurem os aplicativos deles para que aceitem imagens nas duas orientações (paisagem ou retrato).

setRequestMultipleImages: alguns recursos de imagens contêm uma série de imagens em vez de apenas uma. Quando esse valor é definido como "true", seu aplicativo indica que está preparado para exibir todas as imagens dos recursos que têm mais de uma imagem. Quando esse valor é definido como "false" (configuração padrão), seu aplicativo instrui o SDK a fornecer somente a primeira imagem dos recursos que contêm uma série de imagens.

Se withNativeAdOptions não for chamado durante a criação de um AdLoader, o valor padrão de cada opção será usado.

setAdChoicesPlacement()

Por padrão, a sobreposição das Opções de anúncios é configurada para o canto superior direito. É possível alterar o posicionamento da renderização dessa sobreposição nos aplicativos por meio da configuração dessa propriedade como um dos seguintes valores:

  • ADCHOICES_TOP_LEFT
  • ADCHOICES_TOP_RIGHT
  • ADCHOICES_BOTTOM_RIGHT
  • ADCHOICES_BOTTOM_LEFT

Carregar o anúncio nativo

Ao concluir a criação de um AdLoader, chame o método loadAd para solicitar um anúncio:

adLoader.loadAd(new PublisherAdRequest.Builder().build());

É importante notar que os AdLoaders usam as mesmas classes PublisherAdRequest dos banners e intersticiais. É possível usar os métodos dessa classe para adicionar informações de segmentação, do mesmo modo que você faria com outros tipos de anúncios.

Um único AdLoader pode fazer várias solicitações, contanto que elas sejam feitas uma de cada vez. Ao reutilizar um AdLoader, aguarde a finalização de cada solicitação antes de chamar o loadAd novamente para iniciar a próxima. Se você precisar solicitar vários anúncios em paralelo, poderá usar vários objetos AdLoader.

Quando solicitar anúncios

Os aplicativos que exibem anúncios nativos podem solicitá-los antes do momento em que eles serão exibidos de fato. Em muitos casos, essa é uma prática recomendada. Por exemplo, considere um aplicativo cuja lista de itens exibidos inclui anúncios nativos. Esse aplicativo pode carregar anúncios nativos da lista inteira, sabendo que alguns serão exibidos somente depois que o usuário rolar a visualização e que alguns podem nem sequer ser exibidos.

A busca prévia de anúncios é uma ótima técnica, mas é importante que os editores não mantenham anúncios antigos nas listas por muito tempo sem exibi-los. Os objetos de anúncios nativos mantidos por mais de uma hora sem exibição devem ser descartados e substituídos por novos anúncios de uma nova solicitação.

Como exibir formatos de anúncios definidos pelo sistema

Quando um anúncio nativo é carregado, o SDK invoca o listener do formato de anúncio correspondente. Dessa forma, seu aplicativo fica responsável por exibir o anúncio, embora não tenha que fazer isso imediatamente. Para facilitar a exibição de formatos de anúncios definidos pelo sistema, o SDK oferece alguns recursos úteis.

As classes de visualização do anúncio

Para cada um dos formatos definidos pelo sistema, existe uma classe de visualização do anúncio correspondente: NativeAppInstallAdView para anúncios de instalação do app e NativeContentAdView para anúncios de conteúdo. Essas classes de visualização do anúncio são ViewGroups que os editores devem usar como a origem dos anúncios nativos do formato correspondente. Um NativeContentAdView único, por exemplo, corresponde a um anúncio de conteúdo único. As visualizações usadas para exibir os recursos desse anúncio (o ImageView que exibe o recurso de captura de tela, por exemplo) devem ser filhas do objeto NativeContentAdView.

A hierarquia de visualizações de um anúncio de conteúdo que usou um RelativeLayout para exibir os recursos pode ter a seguinte aparência:

As classes de visualização do anúncio também fornecem métodos que fazem o registro da visualização usada pelos recursos individuais, além de outro método para registrar o próprio objeto NativeAd. O registro de visualizações desse modo permite que o SDK automaticamente realize tarefas como:

  • registro de cliques
  • registro de impressões (quando o primeiro pixel fica visível na tela)
  • exibição da sobreposição das Opções de anúncios para os criativos de preenchimento nativo

Sobreposição das Opções de anúncios

Quando um anúncio de preenchimento é retornado, uma visualização de anúncio é adicionada a uma sobreposição das Opções de anúncio pelo SDK. Se seu aplicativo usar preenchimento de anúncios nativos, deixe um espaço no canto de sua preferência da visualização do anúncio nativo para o logotipo das Opções de anúncios, que é automaticamente inserido. Além disso, é importante que a sobreposição das Opções de anúncios esteja facilmente visível. Escolha cores do segundo plano e imagens adequadas. Para mais informações sobre a aparência e função da sobreposição, consulte as diretrizes de implementação do preenchimento nativo.

Exemplo de código

Estas são as etapas para a exibição de um formato de anúncio nativo definido pelo sistema:

  1. Criar uma instância da classe correta de visualização do anúncio.
  2. Para os recursos de anúncios a serem exibidos:
    1. Preencher a visualização de recursos com o recurso no objeto do anúncio nativo.
    2. Registrar a visualização do recurso com a classe ViewGroup.
  3. Registrar o objeto do anúncio nativo com a classe ViewGroup.

Veja o exemplo de uma função que exibe um NativeContentAd:

private void displayContentAd(ViewGroup parent, NativeContentAd contentAd) {
    // Inflate a layout and add it to the parent ViewGroup.
    LayoutInflater inflater = (LayoutInflater) parent.getContext()
            .getSystemService(Context.LAYOUT_INFLATER_SERVICE);
    NativeContentAdView adView = (NativeContentAdView) inflater
            .inflate(R.layout.my_content_ad, parent);

    // Locate the view that will hold the headline, set its text, and call the
    // NativeContentAdView's setHeadlineView method to register it.
    TextView headlineView = (TextView) adView.findViewById(R.id.contentad_headline);
    headlineView.setText(contentAd.getHeadline());
    adView.setHeadlineView(headlineView);

    ...
    // Repeat the above process for the other assets in the NativeContentAd
    // using additional view objects (Buttons, ImageViews, etc).
    ...

    // Call the NativeContentAdView's setNativeAd method to register the
    // NativeAdObject.
    adView.setNativeAd(contentAd);

    // Place the AdView into the parent.
    parent.addView(adView);
}

Vamos analisar as tarefas individuais:

Como aumentar o layout

LayoutInflater inflater = (LayoutInflater) parent.getContext()
        .getSystemService(Context.LAYOUT_INFLATER_SERVICE);
NativeContentAdView adView = (NativeContentAdView) inflater
        .inflate(R.layout.my_content_ad, parent);

Nesse exemplo, estamos aumentando um layout XML que contém visualizações de exibição de um anúncio de conteúdo e, em seguida, localizando uma referência ao NativeContentAdView, que é o elemento principal dele. Essa é uma ótima maneira de dar os primeiros passos. No entanto, você também poderá reutilizar um NativeContentAdView existente se houver um no seu fragmento ou na sua atividade, ou até mesmo criar uma instância dinamicamente sem usar um arquivo de layout.

Como preencher e registrar as visualizações de recursos

TextView headlineView = (TextView) adView.findViewById(R.id.contentad_headline);
headlineView.setText(contentAd.getHeadline());
adView.setHeadlineView(headlineView);

Aqui, estamos localizando a visualização que será usada para exibir o título. Para fazer isso, definimos o texto dela usando o recurso da string fornecida pelo contentAd e registrando-o com o objeto NativeContentAdView. O processo de localizar a visualização, definir o valor dela e registrá-la com a classe de visualização do anúncio deve ser repetido para todos os recursos fornecidos pelo objeto do anúncio nativo.

Como registrar o objeto do anúncio nativo

adView.setNativeAd(contentAd);

Essa etapa final registra o objeto do anúncio nativo com a visualização que é responsável por exibi-lo.

Como carregar formatos de anúncios nativos personalizados

Como criar um AdLoader

Como ocorre com os formatos de anúncios definidos pelo sistema, os formatos de anúncios nativos personalizados são carregados usando a classe AdLoader:

AdLoader adLoader = new AdLoader.Builder(context, "/6499/example/native")
    .forCustomTemplateAd("10063170",
      new NativeCustomTemplateAd.OnCustomTemplateAdLoadedListener() {
          @Override
          public void onCustomTemplateAdLoaded(NativeCustomTemplateAd ad) {
              // Show the custom template and record an impression.
          }
      },
      new NativeCustomTemplateAd.OnCustomClickListener() {
          @Override
          public void onCustomClick(NativeCustomTemplateAd ad, String s) {
              // Handle the click action
          }
      })
    .withAdListener( ... )
    .withNativeAdOptions( ... )
    .build();

Da mesma forma que o método forAppInstallAd configura o AdLoader para solicitar um anúncio de instalação do app, o método forCustomTemplateAd define o mesmo valor para executar anúncios de modelos personalizados. Há três parâmetros passados para o método:

  • O ID do modelo personalizado que o AdLoader deve solicitar. Os formatos de anúncios nativos têm um valor de ID de modelo associados a eles. Esse parâmetro indica qual modelo o AdLoader deve solicitar segundo as configurações do seu aplicativo.
  • Um OnCustomTemplateAdLoadedListener 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 mais informações sobre esse listener, consulte a seção "Como tratar cliques e impressões" abaixo.

É possível configurar um bloco de anúncios único para exibir mais de um modelo de criativo. Por esse motivo, forCustomTemplateAd pode ser chamado várias vezes com IDs de modelo únicos com a finalidade de preparar o carregador de anúncios para mais de um formato de anúncios nativos personalizados.

IDs de modelo

Os IDs de modelo usados para referência exclusiva de formatos de anúncios nativos personalizados podem ser encontrados na IU do DFP em Criativos > seção Formatos de anúncios nativos da guia Exibição:

Os IDs de modelo dos formatos de anúncios nativos personalizados são exibidos abaixo dos nomes deles. Quando você clica em um dos nomes, é exibida uma tela de detalhe que mostra informações sobre os campos do modelo:

Nessa tela, é possível adicionar, editar e remover campos individuais. Observe a coluna ID variável à direita. Esses IDs são usados para acessar os recursos individuais. Discutiremos mais sobre eles na próxima seção.

Como exibir formatos de anúncios nativos personalizados

Os formatos de anúncios nativos personalizados apresentam uma diferença básica em relação àqueles definidos pelo sistema: os editores podem definir seus próprios "modelos", ou listas 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. Como a função da classe NativeCustomTemplateAd é tratar os formatos de anúncios nativos personalizados definidos no DFP, ela não tem getters específicos para os recursos. Ela oferece métodos como getText e getImage, que usam o ID variável de um campo do modelo como parâmetro.
  2. Não existe uma classe de visualização de anúncio dedicada como NativeContentAdView para usar com o NativeCustomTemplateAd. Você pode usar um FrameLayout, um RelativeLayout ou qualquer outra opção que seja viável para a sua experiência do usuário.
  3. Como não existe uma classe ViewGroup dedicada, não é necessário registrar as visualizações que você usa para exibir os recursos do anúncio. Com isso, você se poupa do trabalho de criar algumas linhas de código ao exibir o anúncio. No entanto, você terá um pouco mais de trabalho para tratar os cliques posteriormente.

Veja o exemplo de uma função que exibe um NativeCustomTemplateAd:

public void displayCustomTemplateAd (ViewGroup parent,
                                     NativeCustomTemplateAd customTemplateAd) {
    // 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_template_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(customTemplateAd.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(
            nativeCustomTemplateAd.getImage("MainImage").getDrawable());

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

Como tratar cliques e impressões dos formatos de anúncios nativos personalizados

Com os formatos de anúncios nativos personalizados, seu aplicativo fica responsável por registrar as impressões e informar os eventos de cliques ao SDK.

Como registrar as impressões

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

myCustomTemplateAd.recordImpression();

O SDK evita automaticamente o registro de impressões duplicadas para uma única solicitação, caso seu aplicativo chame o método duas vezes para o mesmo anúncio por engano.

Como informar cliques

Para informar ao SDK que uma visualização de recurso recebeu um clique, chame o método performClick no NativeCustomTemplateAd correspondente e passe o nome do recurso que foi clicado. Por exemplo, se você tivesse um recurso chamado "MainImage" no seu modelo personalizado e quisesse informar um clique no ImageView que correspondesse àquele recurso, seu código teria a seguinte aparência:

myCustomTemplateAd.performClick("MainImage");

É importante ressaltar que não há necessidade de chamar esse método para cada visualização associada ao seu anúncio. Se você tivesse outro campo chamado "Caption" que deveria ser exibido, mas não estar disponível para cliques ou toques do usuário, seu aplicativo não teria que chamar performClick para essa visualização do recurso.

Como responder às ações de cliques em anúncios personalizados

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

  1. Invocar o OnCustomClickListener do AdLoader, caso ele tenha sido fornecido.
  2. Tentar localizar um resolvedor de conteúdo para cada um dos URLs de links profundos do anúncio e iniciar o primeiro que conseguir resolver.
  3. Abrir um navegador e acessar o URL de destino padrão do anúncio.

O método forCustomTemplateAd aceita um OnCustomClickListener. Se você passar um objeto do listener, na verdade o SDK invocará o método onCustomClick dele e não realizará mais nenhuma ação. No entanto, se você passar um valor nulo como o listener, o SDK recorrerá aos URLs de destino e/ou de link profundo registrado com o anúncio.

Os listeners de cliques em anúncios personalizados permitem que seu aplicativo decida a melhor ação a ser realizada como resposta a um clique, seja atualizar a IU, iniciar uma nova atividade ou somente registrar o clique. Veja um exemplo em que há um simples registro de um clique:

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

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

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

Como testar o código de anúncio nativo

Anúncios de vendas diretas

Se você tiver interesse em testar anúncios nativos de vendas diretas, poderá usar esse ID de bloco de anúncios do DFP:

/6499/example/native

Ele foi configurado para exibir amostras de anúncios de instalação do app e de conteúdo, além de um formato de anúncio nativo personalizado com os seguintes recursos:

  • Headline (texto)
  • MainImage (imagem)
  • Caption (texto)

O ID de modelo do formato de anúncio nativo personalizado é 10063170.

Anúncios de preenchimento nativo

Para testar o comportamento de anúncios de preenchimento nativo, use este bloco de anúncios do DFP:

/6499/example/native-backfill

Ele exibe anúncios de instalação do app e de conteúdo que incluem a sobreposição das Opções de anúncios.

Lembre-se de atualizar seu código para que ele consulte os IDs de modelo e o bloco de anúncios reais antes de colocá-lo em execução.

Enviar comentários sobre…

SDK for DFP Users on Android
Precisa de ajuda? Acesse nossa página de suporte.