Ao ler a documentação do Sandbox de privacidade do Android, use o botão Prévia para desenvolvedores ou Beta para selecionar a versão do programa com que você está trabalhando, porque as instruções podem variar.
A API Topics reconhece indicadores de interesse gerais no dispositivo com base em um pelo uso do app pelo usuário. Esses indicadores, chamados de temas, são compartilhados com os anunciantes para oferecer suporte à publicidade com base em interesses sem rastrear usuários individuais apps. Saiba mais sobre a API Topics na proposta de design. Importante: selecione o botão "Versão das extensões do SDK" ou "Visualização para desenvolvedores" para: escolha a versão do programa com que você está trabalhando, pois as instruções podem variar.
Configurar
Use o SDK do Sandbox de privacidade do Android mais recente para ter a versão mais atualizada das APIs que preservam a privacidade. É necessário incluir uma permissão e criar uma configuração do Ad Services no manifesto para que o app use a API Topics:
<uses-permission android:name="android.permission.ACCESS_ADSERVICES_TOPICS" />
Faça referência a uma configuração de serviços de publicidade no elemento <application>
do seu
manifesto:
<property android:name="android.adservices.AD_SERVICES_CONFIG"
android:resource="@xml/ad_services_config" />
Especifique o recurso XML dos serviços de publicidade referenciados no manifesto, como
res/xml/ad_services_config.xml
. Use o atributo allowAllToAccess
para
conceder acesso a todos os SDKs, ou o atributo allowSdksToAccess
para conceder acesso
a SDKs individuais. Saiba mais sobre as permissões dos serviços de anúncios e o controle de acesso
do SDK.
<ad-services-config>
<topics allowAllToAccess="true" />
</ad-services-config>
Além disso, você precisa ativar o acesso à API Topics (desativada por padrão) com esses comandos adb.
adb shell device_config put adservices ppapi_app_signature_allow_list \"\*\"
adb shell setprop debug.adservices.disable_topics_enrollment_check true
A principal funcionalidade da API Topics fica no método
getTopics()
dentro do objeto TopicsManager
, como mostrado neste
exemplo:
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)
Para usar esse método, inicialize o objeto TopicsManager
e os parâmetros
necessários para receber dados de temas. A GetTopicsRequest
transmite as informações necessárias
para extrair os dados da API Topics, incluindo uma sinalização para indicar se o autor da chamada vai
atuar como um observador ou não. Quando não atuar como observador, a
chamada getTopics
vai retornar um tema da época anterior, mas não
vai influenciar os dados do tema para a próxima época. O callback OutcomeReceiver
processa o resultado de forma assíncrona. Exemplo:
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");
}
};
Solicitar um conjunto de temas
Quando a configuração estiver pronta, você vai poder fazer uma chamada para receber uma GetTopicsResponse
como resultado do método getTopics()
:
Kotlin
mTopicsManager.getTopics(mTopicsRequestBuilder.build(), mExecutor,
mCallback as OutcomeReceiver<GetTopicsResponse, java.lang.Exception>)
Java
mTopicsManager.getTopics(mTopicsRequestBuilder.build(), mExecutor, mCallback);
A invocação acima vai fornecer uma lista de objetos de temas que contêm valores de ID correspondentes aos tópicos na taxonomia de código aberto relevantes ao usuário ou a um erro pertinente. Os temas vão ser parecidos com este exemplo:
/Internet & Telecom/Text & Instant Messaging
Consulte a taxonomia (link em inglês) para uma lista de possíveis temas que podem ser retornados. A taxonomia é de código aberto, e você pode registrar as mudanças sugeridas usando o botão de feedback na parte de cima da página.
Testar
A API Topics fornece temas relevantes e atualizados com base no uso do app. Essa versão antecipada
oferece uma prévia dos comportamentos da API, e vamos melhorar a qualidade dos
temas em versões futuras.
Para ter a experiência mais completa, recomendamos um ambiente de teste com vários
apps em que você chame getTopics()
para ver como os temas são selecionados. O repositório do SDK
Runtime e de APIs para preservação de privacidade (em inglês) no GitHub contém um conjunto de
projetos individuais do Android Studio para ajudar você a começar, incluindo exemplos
que demonstram como inicializar e chamar a API Topics.
O cálculo dos temas é realizado no final de uma "época". Por padrão, cada época tem sete dias de duração, mas você pode modificar esse intervalo para extrair um resultado. Este comando do shell do Android Debug Bridge encurta a duração da época para 5 minutos:
adb shell device_config put adservices topics_epoch_job_period_ms 300000
Você pode confirmar o valor de topics_epoch_job_period_ms
com get
:
adb shell device_config get adservices topics_epoch_job_period_ms
Para acionar manualmente o cálculo da época, execute este comando:
adb shell cmd jobscheduler run -f com.google.android.adservices.api 2
Além de usar o app de exemplo, você pode usar o Colab
para testar diferentes combinações de informações do app com o classificador
de temas. Use o Colab para conferir os tipos de resultados que seu app provavelmente
terá ao chamar getTopics
.
Limitações
Para ver uma lista de recursos em desenvolvimento para a API Topics, consulte as notas da versão.
Como informar bugs e problemas
Seu feedback é uma parte crucial do Sandbox de privacidade no Android. Avise nossa equipe sobre problemas encontrados ou ideias para melhorar esse recurso.
Recomendados para você
- Observação: o texto do link aparece quando o JavaScript está desativado.
- Guia do desenvolvedor Android para a API Protected Audience
- Notas de lançamento
- Configurar AdServices {:#configure-adservices}