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.

Nota: Hay una nueva biblioteca de Jetpack que permite la integración con Privacy APIs que preservan la privacidad de Sandbox (Topics, Protected Audience y Informes de atribución. Puedes usar esta biblioteca como acceso directo Este es un reemplazo de las APIs de Privacy Sandbox que se proporcionan en el SDK de la extensión.

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

De manera opcional, para recibir informes de depuración con 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 las APIs

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 del acceso a los recursos que administran las APIs de tu app SDK incorporado.

Nota: Configurar servicios de anuncios específicos es opcional. y solo es necesario cuando el desarrollador de una app quiere cambiar o restringir el acceso a una API, ya que todo el acceso se otorga de forma predeterminada.

En tu manifiesto, especifica una propiedad adservicesConfig como se muestra a continuación en las siguientes 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 emisor.

Como alternativa, puedes usar el atributo allowAdPartnersToAccess para otorgar acceso detallado a las APIs 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.

Nota: Para acceder a las APIs de Privacy Sandbox en la versión más reciente de la extensión del SDK de AdServices y en la Versión preliminar para desarrolladores, debes completar el proceso de inscripción.

Las plataformas de tecnología publicitaria deberían asegurarse de que los clientes acceso a las APIs necesarias que preservan la privacidad en la configuración de los servicios de anuncios.

Nota: Debido a un error conocido, debes establecer allowAllToAccess en true cuando realices pruebas locales.

En el siguiente ejemplo, se muestra cómo especificar un acceso amplio para permitir cualquier inscripción Acceso mediante ID de cuenta 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>

Nota: Si la inscripción está inhabilitada para la API de Topics o la API de Protected Audience mediante comandos adb, la app puede acceder a las APIs relacionadas independientemente de controles de acceso especificados en 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 simplifica la integración 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 que preservan la privacidad, la biblioteca comprueba la disponibilidad del 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 que tiene un AdServices específico de la API de Kubernetes. 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 de SDK y a las APIs que preservan la privacidad se limita a las apps con una actividad visible o con una RunningAppProcessInfo de IMPORTANCE_FOREGROUND.