Configurar o AdServices para Android

Siga as instruções abaixo para declarar permissões específicas da API e configurar o acesso do SDK aos recursos gerenciados pela API de destino.

Declarar permissões específicas da API AdServices

O acesso a cada PPAPI requer uma permissão normal dos serviços de publicidade. No manifesto, declare as permissões de acesso que correspondem às APIs necessárias no app ou SDK.

API Attribution Reporting

<uses-permission android:name="android.permission.ACCESS_ADSERVICES_ATTRIBUTION" />

API Attribution Reporting (com relatórios de depuração):

<uses-permission android:name="android.permission.ACCESS_ADSERVICES_ATTRIBUTION" />
<uses-permission android:name="android.permission.ACCESS_ADSERVICES_AD_ID" />

API de público-alvo personalizado, Protected Audience:

<uses-permission android:name="android.permission.ACCESS_ADSERVICES_CUSTOM_AUDIENCE" />

API Topics:

<uses-permission android:name="android.permission.ACCESS_ADSERVICES_TOPICS" />

Se quiser receber relatórios de depuração com a API Attribution Reporting, inclua a permissão AD_ID:

<uses-permission android:name="android.permission.ACCESS_ADSERVICES_AD_ID" />

Se o projeto tiver dependências em módulos ou SDKs, eles já podem declarar as permissões necessárias dos serviços de publicidade nos arquivos de manifesto. Por padrão, o build do Gradle mescla todos os arquivos de manifesto em um único arquivo, empacotado no app. Use a visualização manifesto integrado para verificar se as permissões corretas são usadas.

Se for necessário impedir que qualquer permissão seja mesclada no seu app por meio de dependências, por exemplo, SDKs, inclua o marcador de nó remove para as permissões específicas. O exemplo a seguir mostra como evitar a mesclagem da permissão da API Topics.

<uses-permission android:name="android.permission.ACCESS_ADSERVICES_TOPICS"
    tools:node="remove" />

Configurar serviços de publicidade específicos das APIs

Semelhante às permissões de acesso à PPAPI, cada API tem uma entrada correspondente na configuração dos serviços de publicidade. Essa configuração oferece acesso de controle refinado a recursos gerenciados pelas APIs no seu app ou SDK incorporado. No manifesto, especifique uma propriedade adservicesConfig, conforme mostrado no exemplo abaixo:

<application ...>
      ...
    <property android:name="android.adservices.AD_SERVICES_CONFIG"
        android:resource="@xml/ad_services_config" />

      ...
</application>

Especifique o recurso XML dos serviços de publicidade referenciados no manifesto, como res/xml/ad_services_config.xml. Para cada API de preservação de privacidade aplicável ao seu app (ou SDK incorporado), defina o atributo allowAllToAccess como true para conceder acesso aos autores de chamadas.

Como alternativa, é possível usar o atributo allowAdPartnersToAccess para conceder acesso detalhado à API para cada adtech. Será necessário fornecer uma lista de IDs de conta de registro de desenvolvedor recebidos por meio do registro. Se o atributo allowAllToAccess estiver definido como true, ele vai ter precedência sobre qualquer ID de conta de registro especificado no atributo allowAdPartnersToAccess.

As plataformas de adtech também precisam garantir que os clientes do seu app concedam corretamente o acesso às APIs de preservação de privacidade necessárias na configuração dos serviços de anúncio.

O exemplo abaixo mostra como especificar o acesso amplo para permitir o acesso ao ID de conta de registro a todas as APIs que preservam a privacidade:

<ad-services-config>
   <!-- Attribution API -->
   <attribution allowAllToAccess="true" />

   <!-- Topics API -->
   <topics allowAllToAccess="true" />

   <!-- Protected Audience on Android API -->
   <custom-audiences allowAllToAccess="true" />
</ad-services-config>

O exemplo a seguir mostra como especificar acesso detalhado a cada API que preserva a privacidade para IDs de conta de registro específicos:

<ad-services-config>
    <!-- Attribution API -->
    <attribution allowAdPartnersToAccess="ENROLLMENT-ID" allowAllToAccess="false" />

    <!-- Topics API -->
    <includes-sdk-library name="ENROLLMENT-ID" />
    <topics allowAdPartnersToAccess="ENROLLMENT-ID" allowAllToAccess="false" />

    <!-- Protected Audience on Android API -->
    <custom-audiences allowAdPartnersToAccess="ENROLLMENT-ID" allowAllToAccess="false" />
</ad-services-config>

Declarar dependências da biblioteca do Jetpack

Use a biblioteca ads-adservices do Jetpack 1.0.0-beta01 ou mais recente para fazer a integração com as APIs do Sandbox de privacidade. Você pode usar essa biblioteca para abstrair o app dos detalhes no nível da plataforma e simplificar a integração com APIs que preservam a privacidade.

  1. Adicione um repositório Maven ao seu projeto.
  2. Declare as dependências de biblioteca do ads-adservices do Jetpack no arquivo build.gradle do app ou módulo.
  3. Use APIs dos pacotes androidx.privacysandbox.ads.adservices.*.
  4. A biblioteca ads-adservices do Jetpack oferece suporte à corrotina incorporada do Kotlin. Talvez seja necessário incorporar as dependências com reconhecimento de ciclo de vida adequadas para que seu projeto gerencie escopos de corrotinas.

Conferir a disponibilidade da versão das extensões de serviços do anúncio

Se você estiver usando a biblioteca ads-services do Jetpack para integrar com APIs que preservam a privacidade, a biblioteca vai verificar a disponibilidade das APIs solicitadas na função obtain(). A função vai retornar um valor nulo se a API solicitada não estiver disponível no dispositivo. O exemplo a seguir ilustra como inicializar TopicsManager para a API Topics. Funciona de forma parecida com o acesso a outras APIs que preservam a privacidade.

Kotlin 

import androidx.privacysandbox.ads.adservices.topics.TopicsManager

// The initialization function will return null if the requested
// functionality is not available on the device.
val topicsManager = TopicsManager.obtain(context)

Java 

import androidx.privacysandbox.ads.adservices.topics.TopicsManager;

// The initialization function will return null if the requested
// functionality is not available on the device.
TopicsManager topicsManager = TopicsManager.obtain(context);

Se você estiver usando as APIs AdServices diretamente no SDK da extensão, confira a versão de extensões do AdServices que inclui as APIs AdServices que você quer usar. Na referência da API, você pode identificar a versão em que uma API AdServices específica foi introduzida. Por exemplo, a referência da API para a classe TopicsManager indica que ela foi "adicionada na versão 4 das extensões de serviços de publicidade". Use as seguintes verificações condicionais para validar extensões do SDK que contêm APIs AdServices.

Kotlin 

import android.os.ext.SdkExtensions

if (SDK_INT >= Build.VERSION_CODES.R && // The extensions API is available since R.
   SdkExtensions.getExtensionVersion(SdkExtensions.AD_SERVICES) >= 4) {

    // AdServices API is available.
...
}

Java 

import android.os.ext.SdkExtensions;

if (SDK_INT >= Build.VERSION_CODES.R && // The extensions API is available since R.
   SdkExtensions.getExtensionVersion(SdkExtensions.AD_SERVICES) >= 4) {

    // AdServices API is available.
...
}

Limitação de acesso em primeiro plano

Para oferecer transparência, o acesso ao SDK Runtime e às APIs de preservação de privacidade é limitado a apps com uma atividade visível ou com uma RunningAppProcessInfo de IMPORTANCE_FOREGROUND.