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.
La API de Topics infiere indicadores de interés generales en el dispositivo según un el uso de la app por parte del usuario. Estos indicadores, llamados temas, se comparten con los anunciantes para respaldar la publicidad basada en intereses sin realizar un seguimiento de los usuarios individuales en de Google Chat. Obtén más información sobre la API de Topics en la propuesta de diseño. Importante: Selecciona el botón Versión de las extensiones del SDK o Versión preliminar para desarrolladores para elige la versión del programa con la que estás trabajando, ya que las instrucciones pueden variar.
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:
Kotlin
fun getTopics(
getTopicsRequest: GetTopicsRequest,
executor: Executor,
callback: OutcomeReceiver<GetTopicsResponse, Exception>
) { }
Java
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:
Kotlin
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")
}
}
Java
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()
:
Kotlin
mTopicsManager.getTopics(mTopicsRequestBuilder.build(), mExecutor,
mCallback as OutcomeReceiver<GetTopicsResponse, java.lang.Exception>)
Java
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.
Recomendaciones para ti
- Nota: El texto del vínculo se muestra cuando JavaScript está desactivado
- Guía para desarrolladores de la API de Protected Audience en Android
- Notas de la versión
- Cómo configurar AdServices {:#configure-adservices}