Cómo configurar AdServices para Android

Sigue las instrucciones que se indican a continuación para declarar permisos específicos de APIs y configurar el acceso de SDKs a los recursos que administra la API objetivo.

Declara permisos específicos de la API de AdServices

El acceso a cada PPAPI requiere un permiso normal de servicios de anuncios. En tu manifiesto, declara los permisos de acceso adecuados que correspondan a las APIs necesarias en tu app o SDK.

API de Attribution Reporting:

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

API de Attribution Reporting (con informes de depuración):

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

API de Protected Audience/Custom Audience:

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

API de Topics:

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

(Opcional) Si quieres recibir informes de depuración con la API de Attribution Reporting, incluye el permiso AD_ID:

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

Si tu proyecto tiene dependencias en módulos o SDKs, es posible que ya declaren los permisos necesarios de los servicios de anuncios en sus archivos de manifiesto. De forma predeterminada, la compilación de Gradle combina todos los archivos de manifiesto en uno solo que se empaqueta en la app. Usa la vista Manifiesto combinado para verificar que se usen los permisos correctos.

Si necesitas evitar que los permisos se combinen con tu app a través de dependencias, como los SDKs, incluye el marcador de nodos remove para los permisos en particular. En el siguiente ejemplo, se muestra cómo evitar que se combine el permiso de Topics.

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

Configura servicios de anuncios específicos de la API

Al igual que los permisos de acceso a la PPAPI, cada API tiene una entrada correspondiente en la configuración de servicios de anuncios. Esta configuración te brinda un control detallado de los recursos que administran las APIs de tu app o SDK incorporado. En tu manifiesto, especifica una propiedad adservicesConfig, como se muestra en el siguiente ejemplo:

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

      ...
</application>

Especifica el recurso XML de servicios de anuncios al que se hace referencia en el manifiesto, como res/xml/ad_services_config.xml. Para cada API que preserva la privacidad aplicable a tu app (o SDK incorporado), establece el atributo allowAllToAccess en true para otorgar acceso a cualquier llamador.

Como alternativa, puedes usar el atributo allowAdPartnersToAccess para otorgar acceso detallado a la API para cada tecnología publicitaria. Deberás proporcionar una lista de los IDs de las cuentas de inscripción de desarrollador obtenidos con la inscripción. Si el atributo allowAllToAccess está configurado en true, este tiene prioridad sobre cualquier ID de las cuentas de inscripción especificado en el atributo allowAdPartnersToAccess.

Las plataformas de tecnología publicitaria también deben asegurarse de que sus clientes de apps otorguen acceso a las APIs que preservan la privacidad necesarias en la configuración de los servicios de anuncios.

En el siguiente ejemplo, se muestra cómo especificar un acceso amplio para permitir el acceso de cualquier ID de la cuenta de inscripción a todas las APIs que preservan la privacidad:

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

En el siguiente ejemplo, se muestra cómo especificar un acceso detallado a cada API que preserva la privacidad para IDs de cuentas de inscripción específicas:

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

Declara dependencias de la biblioteca de Jetpack

Usa la biblioteca de Jetpack ads-adservices 1.0.0-beta01 o una posterior para integrar con las APIs de Privacy Sandbox que preservan la privacidad. Puedes usar esta biblioteca para abstraer tu app de los detalles a nivel de la plataforma y simplificar la integración con APIs que preservan la privacidad.

  1. Agrega un repositorio de Maven a tu proyecto.
  2. Declara dependencias de la biblioteca de Jetpack ads-adservices en el archivo build.gradle de tu app o módulo.
  3. Usa las APIs de los paquetes androidx.privacysandbox.ads.adservices.*.
  4. La biblioteca de Jetpack ads-adservices proporciona compatibilidad integrada con corrutinas de Kotlin. Quizás debas incorporar las dependencias que tienen en cuenta el ciclo de vida y que son adecuadas para tu proyecto para administrar los alcances de las corrutinas.

Cómo consultar la disponibilidad de la versión de las extensiones de servicios de anuncios

Si usas la biblioteca de Jetpack ads-services para la integración con las APIs que preservan la privacidad, la biblioteca verifica la disponibilidad de las APIs solicitadas en la función obtain(). La función muestra un resultado nulo si la API solicitada no está disponible en el dispositivo. En el siguiente ejemplo, se muestra cómo inicializar TopicsManager para la API de Topics. Funciona de manera similar para acceder a otras APIs que preservan la privacidad.

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);

Si usas directamente las APIs de AdServices en el SDK de extensiones, verifica que la versión de las extensiones de AdServices incluya las APIs de AdServices que desees usar. En la referencia de la API, puedes identificar la versión en la que se presenta una API de AdServices específica. Por ejemplo, la referencia de la API de la clase TopicsManager indica que se agregó en Ad Services Extensions 4. Usa las siguientes verificaciones condicionales para validar las extensiones del SDK que contienen las APIs de 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.
...
}

Limitación del acceso en primer plano

Para brindar transparencia, el acceso al entorno de ejecución del SDK y a las APIs que preservan la privacidad se limita a las apps con una actividad visible o con RunningAppProcessInfo de IMPORTANCE_FOREGROUND.