Guia da API Topics para desenvolvedores

Enviar feedback

A API Topics reconhece indicadores de interesse gerais no dispositivo com base no uso de apps do usuário. Esses indicadores, chamados de temas, são compartilhados com os anunciantes para dar suporte a publicidade com base em interesses sem rastrear usuários individuais em apps. Saiba mais sobre a API Topics na proposta de design.

Configuração

A taxonomia da API Topics é semelhante à taxonomia de código aberto do Chrome (link em inglês), com versões futuras mudando para um sistema específico do Android, incluindo a classificação no dispositivo. Use o SDK da prévia para desenvolvedores do Sandbox de privacidade do Android, que é a única versão do SDK que inclui as APIs que preservam a privacidade. É necessário incluir uma permissão e criar uma configuração de serviços de anúncios para que o app use a API Topics, conforme mostrado abaixo:

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

Faça referência a uma configuração de serviços de anúncios 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:

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

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?, AdServicesException?>?
    ) { }

Java

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

Para usar esse método, inicialize o objeto TopicsManager e os parâmetros necessários para receber dados de temas. Para inicializar parâmetros, crie uma GetTopicsRequest, um Executor e um OutcomeReceiver para o callback. A GetTopicsRequest transmite as informações necessárias para extrair os dados dos temas, o Executor permite que getTopics() seja executado fora da linha de execução de IU e 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 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");

    }
};

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(getTopicsRequest.build(), mExecutor,
        mCallback as OutcomeReceiver<GetTopicsResponse, GetTopicsException>)

Java

mTopicsManager.getTopics(getTopicsRequest.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 ver uma lista de possíveis temas que podem ser retornados. Essa taxonomia está sujeita a mudanças.

Teste

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 conseguir um resultado mais rapidamente usando este comando do shell do Android Debug Bridge:

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

Você pode confirmar o valor de topics_epoch_job_period_ms com getprop:

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

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 o Sandbox de privacidade no Android.