Implementação do AFS em apps para dispositivos móveis (AFSMA) no Android

Pré-requisitos

Este guia de implementação pressupõe que você esteja familiarizado com o seguinte:

Aulas

Para veicular anúncios do AFSMA (também conhecidos como anúncios de altura dinâmica) no seu app, implemente as seguintes classes:

SearchAdView

  • Essa classe é herdada da classe ViewGroup do Android e exibe os anúncios do AFSMA. O SearchAdView faz a solicitação de um anúncio com uma DynamicHeightSearchAdRequest e renderiza os anúncios retornados. A SearchAdView precisa ser adicionada a qualquer um dos grupos de visualizações do app já existentes.
  • O SearchAdView precisa ser instanciado com o contexto em que o SearchAdView está sendo executado, normalmente um Activity.
  • Depois que o SearchAdView for instanciado, é necessário chamar o método setAdSize() com AdSize.SEARCH para solicitar anúncios do AFSMA. Outros valores de enumeração solicitarão anúncios não compatíveis com o AFS em aplicativos para dispositivos móveis.
  • Chame o método setAdUnitId() nesse objeto com seu código de propriedade.

DynamicHeightSearchAdRequest.Builder

  • Esta classe encapsula os parâmetros de solicitação de anúncio. Isso é análogo à configuração de parâmetros nos objetos de solicitação de anúncio JavaScript (opções da página, opções de bloco) para a Web para computadores e dispositivos móveis do AFS.
  • Defina os parâmetros com os setters apropriados. Em outras palavras, chame setQuery() para definir o parâmetro de consulta.

Implementação de exemplo

O exemplo abaixo demonstra o uso de uma Activity para criar uma SearchAdView como uma subvisualização de um ViewGroup. Para solicitar corretamente os anúncios do AFSMA, o objeto SearchAdView precisa chamar o método setAdSize() com AdSize.SEARCH.

//  MainActivity.java implementation
//  (MainActivity is a subclass of Activity)

// Create the SearchAdView
final SearchAdView searchAdView = new SearchAdView(this);

// Set parameter to request for dynamic height search ads
searchAdView.setAdSize(AdSize.SEARCH); // Important!

// Replace with your pub ID (e.g. ms-app-pub-9616389000213823)
searchAdView.setAdUnitId("ms-app-pub-################");

// Add searchAdView to parent view group
...

No mesmo Activity, crie uma DynamicHeightSearchAdRequest.Builder que dite os parâmetros do anúncio que vão ser renderizados na SearchAdView. Os anúncios do AFSMA são configurados da mesma maneira que os anúncios personalizados da rede de pesquisa do AFS. Consulte a Referência dos anúncios personalizados da rede de pesquisa do AFS para detalhes.

// Create the ad request
DynamicHeightSearchAdRequest.Builder builder =
        new DynamicHeightSearchAdRequest.Builder();
builder.setQuery("flowers");
builder.setNumber(2);

// Replace with the ID of a style from your custom search styles
builder.setAdvancedOptionValue("csa_styleId", "0000000001");

// Customization options (set using setters on
// DynamicHeightSearchAdRequest.Builder)
builder.setAdTest(true);

Outras opções de personalização são possíveis definindo outras propriedades no objeto DynamicHeightSearchAdRequest.Builder.

Para fazer uma solicitação de anúncio, chame o método loadAd() com o objeto DynamicHeightSearchAdRequest.Builder do objeto SearchAdView:

searchAdView.loadAd(builder.build());

Opções avançadas

A maioria dos parâmetros de solicitação de anúncio pode ser definida por meio de métodos setter no objeto DynamicHeightSearchAdRequest.Builder. Qualquer parâmetro que não tenha um método setter em DynamicHeightSearchAdRequest.Builder pode ser definido usando pares de chave-valor com o método setAdvancedOptionValue(). Consulte a Referência dos Anúncios personalizados de pesquisa do AFS para uma lista completa de configurações que podem ser definidas com o método setAdvancedOptionValue().

O parâmetro chave precisa ter o prefixo "csa_" para que a propriedade seja definida corretamente.

// Advanced customization options (set using key-value pair)

// Set a parameter (parameter_name) and its value (parameter_value)
// builder.setAdvancedOptionValue("csa_parameter_name", "parameter_value");

// Example: Show visible URL below description
// (domainLinkAboveDescription: false)
builder.setAdvancedOptionValue("csa_domainLinkAboveDescription", "false");

Se você usar o método setter de um parâmetro e o definir usando setAdvancedOptionValue, a segunda chamada vai substituir o valor da primeira.

Como investigar erros

O SearchAdView (searchAdView aqui) contém um método setAdListener() para ajudar você a investigar erros. No mesmo Activity:

searchAdView.setAdListener(new AdListener() {
    @Override
    public void onAdLoaded() {
        // Called when an ad is loaded
        super.onAdLoaded();
        Toast.makeText(MainActivity.this, "Ad Loaded",
                Toast.LENGTH_SHORT).show();
        Log.d(MainActivity.class.getSimpleName(), "Ad Loaded");
    }

    @Override
    public void onAdOpened() {
        // Called when an ad opens an overlay that covers the screen
        super.onAdOpened();
        Toast.makeText(MainActivity.this, "Ad Opened",
                Toast.LENGTH_SHORT).show();
        Log.d(MainActivity.class.getSimpleName(), "Ad Opened");
    }

    @Override
    public void onAdLeftApplication() {
        // Called when an ad leaves the application
        // (to go to the browser for example)
        super.onAdLeftApplication();
        Toast.makeText(MainActivity.this, "Ad Left Application",
                Toast.LENGTH_SHORT).show();
        Log.d(MainActivity.class.getSimpleName(), "Ad Left Application");
    }

    @Override
    public void onAdFailedToLoad(int errorCode) {
        // Called when an ad request failed
        super.onAdFailedToLoad(errorCode);
        Toast.makeText(MainActivity.this, "Ad Failed to Load: " + errorCode,
                Toast.LENGTH_SHORT).show();
        Log.e(MainActivity.class.getSimpleName(), "Ad Failed to Load: " +
                errorCode);
    }
});

As constantes usadas no método de callback onAdFailedToLoad() são descritas na Referência da API.

Preparação para os requisitos de divulgação de dados do Google Play

Em maio de 2021, o Google Play anunciou a nova seção "Segurança dos dados", uma declaração fornecida pelo desenvolvedor sobre práticas de coleta, compartilhamento e segurança de dados de um app.

Esta página ajuda a preencher os requisitos para essa divulgação de dados quanto ao uso do SDK nativo do AFS (também aplicável ao uso do AdSense para Shopping). Nesta página, você encontra informações sobre como os SDKs processam os dados dos usuários finais.

Queremos ser o mais transparente possível com você. No entanto, como desenvolvedor de apps, você é a única pessoa responsável por decidir como responder ao formulário da seção "Segurança dos dados" do Google Play em relação às práticas de coleta, compartilhamento e segurança de dados do usuário final.

Como usar as informações desta página

Esta página lista os dados do usuário final coletados apenas pela versão mais recente do SDK.

Para concluir a divulgação de dados, use o guia sobre tipos de dados do Android e defina o tipo que melhor descreve os dados coletados. Na divulgação de dados, considere também a forma como o app específico compartilha e usa os dados coletados.

Acessos e coletas do SDK dos tipos de dados

Pacotes:

com.google.android.gms:play-services-afs-native

com.google.ads.afsn

Dados coletados automaticamente

O SDK do AFS coleta os dados a seguir automaticamente. Todos os dados são transmitidos para fora do dispositivo para o Google com a finalidade de veicular anúncios e são criptografados em trânsito. As informações pessoais do usuário nunca são coletadas, a menos que sejam enviadas em uma consulta do usuário pelo seu app.

Dados Esses dados são coletados para os seguintes fins...
Endereço IP Resumo:
  • Segurança, conformidade e prevenção contra fraudes
  • Publicidade ou marketing
  • Derivar local aproximado
Detalhe:
O endereço IP é usado no monitoramento de fraudes e abusos, além de ser utilizado para estimar a localização aproximada do usuário.

O local aproximado é usado para garantir que os anúncios veiculados obedeçam às regulamentações locais e fornecer anúncios relevantes à localização geográfica aproximada do usuário.

Atividade em apps
  • Visualizações de página e toques no app
  • Histórico de pesquisa no app
Resumo:
  • Analytics
  • Segurança, conformidade e prevenção contra fraudes
  • Publicidade ou marketing
  • Personalização
Detalhe:
Seu app disponibiliza a consulta do usuário para retornarmos anúncios de pesquisa relevantes para a palavra-chave. Medimos as visualizações e o engajamento (toques) com os anúncios retornados.
Diagnósticos Resumo:
  • Analytics
Detalhe:
O SDK mede a latência de renderização dos anúncios para permitir que melhorias no produto sejam implementadas e medidas. Também enviamos relatórios de erros/falhas e adicionamos outros recursos de instrumentação conforme necessário para entender como os editores usam a funcionalidade.
Identificadores do dispositivo e outros Resumo:
  • Segurança, conformidade e prevenção contra fraudes
  • Publicidade ou marketing
Detalhe:
O ID do dispositivo é usado para ajudar no monitoramento de fraudes e abusos, bem como na medição do desempenho de anúncios.