Guía para desarrolladores de la API de Topics

Envía comentarios

La API de Topics infiere indicadores generales de interés en el dispositivo a partir de las apps que usa un usuario. Estos indicadores, denominados temas, se comparten con los anunciantes para admitir la publicidad basada en intereses sin realizar un seguimiento de los usuarios individuales en todas las apps. Obtén más información sobre la API de Topics en la propuesta de diseño.

Configuración

La taxonomía de Topics es similar a la taxonomía de Chrome de código abierto, con actualizaciones futuras que cambian a un sistema específico de Android, incluida la clasificación integrada en el dispositivo. Asegúrate de usar el SDK de Vista previa para desarrolladores de Privacy Sandbox de Android, ya que esta es la única versión del SDK que incluye las API para preservar la privacidad. Deberás incluir un permiso y crear una configuración de servicios de anuncios para que tu app use la API de Topics, como se muestra a continuación:

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

Haz referencia a una 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 SDK, o el atributo allowSdksToAccess a fin de otorgar acceso a SDK individuales:

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

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

Kotlin

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

Java

public void getTopics (GetTopicsRequest getTopicsRequest, Executor executor,
    OutcomeReceiver<GetTopicsResponse, AdServicesException> callback)

A fin de usar este método, inicializa el objeto TopicsManager y los parámetros necesarios para recibir datos de temas. A fin de inicializar los parámetros, crea un GetTopicsRequest, un Executor y un OutcomeReceiver para la devolución de llamada. GetTopicsRequest pasa la información necesaria para recuperar datos de temas, Executor permite que getTopics() se ejecute fuera del subproceso de IU, y la devolución de llamada OutcomeReceiver controla el resultado de forma asíncrona. Por ejemplo:

Kotlin

private fun topicGetter() {
    val mContext = baseContext
    val mTopicsManager = mContext.getSystemService(TopicsManager::class.java)
    val mExecutor: Executor = Executors.newCachedThreadPool()
    val getTopicsRequest = GetTopicsRequest.Builder(mContext)
    mTopicsManager.getTopics(getTopicsRequest.build(), mExecutor, mCallback)
}

private var mCallback: OutcomeReceiver<GetTopicsResponse, GetTopicsException> =
    object : OutcomeReceiver<GetTopicsResponse, GetTopicsException> {
        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: GetTopicsException) {
            // handle error
            Log.i("Topic", "Error, did not return successfully")
        }
    }

Java

public void TopicGetter() {
    @NonNull Context mContext = getBaseContext();
    TopicsManager mTopicsManager = mContext.getSystemService(TopicsManager.class);
    Executor mExecutor = Executors.newCachedThreadPool();
    GetTopicsRequest.Builder getTopicsRequest = new GetTopicsRequest.Builder(mContext);
    mTopicsManager.getTopics(getTopicsRequest.build(), mExecutor, mCallback);
}

OutcomeReceiver mCallback = new OutcomeReceiver<GetTopicsResponse,
                                                GetTopicsException>() {
    @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 GetTopicsException error) {
        // handle error
        Log.i("Topic", "Error, did not return successfully");

    }
};

Solicita un conjunto de temas

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

Kotlin

mTopicsManager.getTopics(getTopicsRequest.build(), mExecutor,
        mCallback as OutcomeReceiver<GetTopicsResponse, GetTopicsException>)

Java

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

La invocación anterior proporcionará una lista de objetos Topics que contienen valores de ID que corresponden a temas en la taxonomía de código abierto que son relevantes para el 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 está sujeta a cambios.

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 API del entorno de ejecución y la protección de la privacidad de SDK en GitHub contiene un conjunto de proyectos individuales de Android Studio que te ayudarán a comenzar, incluidos ejemplos que muestran cómo inicializar y llamar al método API de Topics.

El cálculo de temas se lleva a cabo al final de una "época". De forma predeterminada, cada época dura 7 días, pero puedes modificar este intervalo para obtener un resultado más rápido mediante el siguiente comando de shell de Android Debug Bridge:

# Shortens the epoch length to 5 minutes.
adb shell setprop debug.adservices.topics_epoch_job_period_ms 300000

Puedes confirmar el valor topics_epoch_job_period_ms con getprop:

adb shell getprop debug.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

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.