Implementa la API de Topics en Android

Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Configuración

Para implementar la API de Topics, primero debes configurar tu entorno de desarrollo. Para ello, sigue estos pasos de configuración:

1. Usa el SDK de Privacy Sandbox para Android más reciente para obtener la versión más reciente de las APIs que preservan la privacidad.

2. Agrega lo siguiente a tu manifiesto:

   • Permiso: Incluye el permiso ACCESS_ADSERVICES_TOPICS para permitir que tu app acceda a la API de Topics:

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

   • Configuración de servicios de anuncios: Haz referencia a un archivo de configuración de servicios de anuncios en el elemento <application> de tu manifiesto.

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

     Especifica el recurso XML de servicios de anuncios al que se hace referencia en el manifiesto, como res/xml/ad_services_config.xml. Usa el atributo allowAllToAccess para otorgar acceso a todos los SDKs, o bien el atributo allowSdksToAccess para otorgar acceso a SDKs individuales. Obtén más información sobre los permisos de los servicios de anuncios y el control de acceso al SDK.

     <ad-services-config>
         <topics allowAllToAccess="true"/>
     </ad-services-config>
     

3. Inscribe tu tecnología publicitaria en Privacy Sandbox para llamar a la API de Topics en tu SDK. Para realizar pruebas locales, puedes inhabilitar la verificación de inscripción de Topics con los siguientes comandos:

   adb shell setprop debug.adservices.disable_topics_enrollment_check true
   

4. Habilita el acceso a la API de Topics. De forma predeterminada, la API de Topics está inhabilitada. Debes habilitarlo con los comandos de ADB:

   adb shell device_config put adservices ppapi_app_signature_allow_list \"\*\"

   adb shell setprop debug.adservices.disable_topics_enrollment_check true

5. Para comenzar tu implementación, bifurca nuestra versión de Java o Kotlin de la app de ejemplo para familiarizarte con la recuperación de temas en un dispositivo.

Solicita un conjunto de temas

La funcionalidad principal de la API de Topics se encuentra en el método getTopics(). en el TopicsManager como se muestra en este ejemplo:

fun getTopics(
        getTopicsRequest: GetTopicsRequest,
        executor: Executor,
        callback: OutcomeReceiver<GetTopicsResponse, Exception>
    ) { }

public void getTopics (@NonNull GetTopicsRequest getTopicsRequest,
    @NonNull Executor executor,
    @NonNull OutcomeReceiver<GetTopicsResponse, Exception> callback)

Si quieres usar este método, inicializa el objeto TopicsManager y los parámetros necesarios para recibir datos de temas. GetTopicsRequest pasa la información necesaria para recuperar los datos de la API de Topics, incluida una marca para indicar si el emisor actuará como observador o no. Cuando no actúa como observador, la llamada getTopics mostrará un tema de la época anterior, pero no influirá en los datos de temas para la siguiente. La devolución de llamada OutcomeReceiver controla el resultado de forma asíncrona. Por ejemplo:

private fun topicGetter() {
    val mContext = baseContext
    val mTopicsManager = mContext.getSystemService(TopicsManager::class.java)
    val mExecutor: Executor = Executors.newCachedThreadPool()
    val shouldRecordObservation = false
    val mTopicsRequestBuilder: GetTopicsRequest.Builder = GetTopicsRequest.Builder()
    mTopicsRequestBuilder.setAdsSdkName(baseContext.packageName)
    mTopicsRequestBuilder.setShouldRecordObservation(shouldRecordObservation)
    mTopicsManager.getTopics(mTopicsRequestBuilder.build(), mExecutor,
        mCallback as OutcomeReceiver<GetTopicsResponse, Exception>)
}
private var mCallback: OutcomeReceiver<GetTopicsResponse, java.lang.Exception> =
object : OutcomeReceiver<GetTopicsResponse, java.lang.Exception> {
    override fun onResult(result: GetTopicsResponse) {
        // handle successful result
        val topicsResult = result.topics
        for (i in topicsResult.indices) {
            Log.i("Topic", topicsResult[i].getTopicId().toString())
        }
        if (topicsResult.size == 0) {
            Log.i("Topic", "Returned Empty")
        }
    }
    override fun onError(error: java.lang.Exception) {
        // handle error
        Log.i("Topic", "Error, did not return successfully")
    }
}

public void TopicGetter() {
    @NonNull Context mContext = getBaseContext();
    TopicsManager mTopicsManager = mContext.getSystemService(TopicsManager.class);
    Executor mExecutor = Executors.newCachedThreadPool();
    boolean shouldRecordObservation = false;
    GetTopicsRequest.Builder mTopicsRequestBuilder = new GetTopicsRequest.Builder();
    mTopicsRequestBuilder.setAdsSdkName(getBaseContext().getPackageName());
    mTopicsRequestBuilder.setShouldRecordObservation(shouldRecordObservation);
    mTopicsManager.getTopics(mTopicsRequestBuilder.build(), mExecutor, mCallback);
}
OutcomeReceiver mCallback = new OutcomeReceiver<GetTopicsResponse, Exception>() {
    @Override
    public void onResult(@NonNull GetTopicsResponse result) {
        //Handle Successful Result
        List<Topic> topicsResult = result.getTopics();
        for (int i = 0; i < topicsResult.size(); i++) {
            Log.i("Topic", topicsResult.get(i).getTopicId().toString());
        }
        if (topicsResult.size() == 0) {
            Log.i("Topic", "Returned Empty");
        }
    }
    @Override
    public void onError(@NonNull Exception error) {
        // Handle error
        Log.i("Topic", "Experienced an error, and did not return successfully");
    }
};

Una vez que tu configuración esté lista, puedes realizar una llamada para recibir un GetTopicsResponse como resultado del método getTopics():

mTopicsManager.getTopics(mTopicsRequestBuilder.build(), mExecutor,
        mCallback as OutcomeReceiver<GetTopicsResponse, java.lang.Exception>)

mTopicsManager.getTopics(mTopicsRequestBuilder.build(), mExecutor, mCallback);

Esta invocación proporcionará una lista de objetos Topics que contienen valores de ID. que corresponden a temas de la taxonomía de código abierto y relevantes usuario o un error relevante. Los temas se parecerán a este ejemplo:

/Internet & Telecom/Text & Instant Messaging

Consulta la taxonomía para obtener una lista de los temas posibles que se pueden mostrar. Esta taxonomía es de código abierto y los cambios sugeridos se pueden registrar con el botón de comentarios en la parte superior de esta página.

Prueba

La API de Topics proporciona temas nuevos y relevantes según el uso de la app. Esta versión anterior ofrece una vista previa de los comportamientos de la API, y mejoraremos la calidad de los temas en comparación con las versiones futuras.

Si deseas obtener la experiencia más completa, te recomendamos un entorno de pruebas con varias apps en el que llames a getTopics() para aprender cómo se seleccionan los temas. El Repositorio de APIs que preserva la privacidad y el entorno de ejecución del SDK en GitHub contiene un conjunto de proyectos individuales de Android Studio que te ayudarán a obtener que incluye ejemplos que muestran cómo inicializar y llamar a la API de Topics.

El cálculo de temas se realiza al final de un ciclo de entrenamiento. De forma predeterminada, cada época dura 7 días, pero puedes modificar este intervalo para obtener un resultado. Este comando de shell Android Debug Bridge acorta la duración a 5 minutos:

adb shell device_config put adservices topics_epoch_job_period_ms 300000

Puedes confirmar el valor topics_epoch_job_period_ms con get:

adb shell device_config get adservices topics_epoch_job_period_ms

Para activar el cálculo de la época de forma manual, ejecuta el siguiente comando:

adb shell cmd jobscheduler run -f com.google.android.adservices.api 2

Además de usar la app de ejemplo, hay un colab que puedes usar para probar diferentes combinaciones y comparar la información de la app con el clasificador de temas. Usa este colab para ver los tipos de resultados que podría obtener tu app cuando llame a getTopics.

Detalles de encriptación

Con la introducción de la encriptación, las llamadas a GetTopics() ahora generarán una respuesta con una lista de objetos EncryptedTopic. Si desencriptas estos resultados, se obtendrá un objeto con el mismo formato JSON del objeto Topic anterior.

La API de Topics admite la implementación única de HPKE (encriptación de clave pública híbrida). Esperamos que el llamador inscrito aloje una clave pública de 32 bits en el extremo de URL de encriptación pública que se proporcionó durante la inscripción. Se espera que estas claves estén codificadas en Base64.

Los objetos EncryptedTopic tienen 3 campos. La lista de temas que se muestran se puede obtener con la clave privada correspondiente a la clave pública.

Para fines de desarrollo, puedes probar la encriptación de la API de Topics inhabilitando la verificación de inscripción. Esto obligaría a la API a usar la clave pública de prueba para cifrando tus respuestas. Puedes desencriptar los temas encriptados con el la clave privada correspondiente.

Limitaciones

A fin de obtener una lista de las funciones en curso para la API de Topics, consulta las notas de la versión.

Informa errores y problemas

Tus comentarios son una parte fundamental de Privacy Sandbox en Android. Avísanos si tienes problemas o ideas para mejorar Privacy Sandbox en Android.

Pasos siguientes

Consulta también

Consulta nuestros recursos para comprender mejor la API de Topics en Android.

• Consulta las apps de ejemplo, las colaboraciones y los videos explicativos de Topics.
• Descubre cómo los usuarios y desarrolladores pueden controlar la API.
• Consulta los recursos de asistencia para formular preguntas, participar y compartir comentarios.