Guía para desarrolladores de la API de Topics

A medida que leas la documentación de Privacy Sandbox en Android, usa el botón Versión preliminar para desarrolladores o Beta para seleccionar la versión del programa con la que estás trabajando, ya que las instrucciones pueden variar.

Enviar comentarios

Configuración

Usa el SDK de Privacy Sandbox en Android más reciente para obtener la versión más reciente de las APIs que preservan la privacidad. Debes incluir un permiso y crear una configuración de servicios de anuncios en tu manifiesto para que tu app use la API de Topics:

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

Además, debes habilitar el acceso a la API de Topics (inhabilitado de forma predeterminada) con estos comandos adb.

adb shell device_config put adservices ppapi_app_signature_allow_list \"*\"

adb shell setprop debug.adservices.disable_topics_enrollment_check true

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:

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

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():

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

mTopicsManager.getTopics(mTopicsRequestBuilder.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 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 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. 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.

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.