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.

Observação: há uma nova biblioteca Jetpack que permite a integração com a privacidade. APIs de preservação de privacidade da Sandbox (Topics, Protected Audience e Relatórios de atribuição. Você pode usar esta biblioteca como um drop-in substituto para as APIs do Sandbox de privacidade fornecidas no SDK da extensão.

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" />

Opcionalmente, para receber relatórios de depuração com a API Attribution Reporting API, 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 controlar o acesso a recursos gerenciados pelas APIs no app ou SDK incorporado.

Observação :a configuração de serviços de publicidade específicos é opcional, e só é necessária quando um desenvolvedor de aplicativos quer alterar ou restringir o acesso a uma API, já que todo o acesso é concedido por padrão.

No manifesto, especifique uma propriedade adservicesConfig, conforme mostrado no seguinte exemplo:

<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 a seu app (ou SDK incorporado), defina o atributo allowAllToAccess como true para conceder acesso a qualquer autor da chamada.

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.

Observação: para acessar as APIs do Sandbox de privacidade na versão mais recente da extensão do SDK do AdServices e na versão da prévia para desenvolvedores, você precisa concluir o processo de registro.

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

Observação: devido a um bug conhecido, defina allowAllToAccess como true ao testar localmente.

O exemplo a seguir mostra como especificar o acesso amplo para permitir qualquer registro acesso ao ID da conta 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>

Observação :se a inscrição estiver desativada para a API Topics ou a API Protected Audience usando comandos adb, o aplicativo pode acessar APIs relacionadas, independentemente controles de acesso especificados em 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 abstraia seu app dos detalhes no nível da plataforma e simplifica a integração com 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 fazer a integração com APIs que preservam a privacidade, a biblioteca verifica a disponibilidade do 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 que um determinado AdServices API é 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 que preservam a privacidade é limitado a apps com uma atividade visível ou com um RunningAppProcessInfo de IMPORTANCE_FOREGROUND.