Implementar a API Topics no Android

bookmark_border Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Configuração

Para implementar a API Topics, é necessário configurar primeiro seu ambiente de desenvolvimento. siga estas etapas de configuração:

1. Use o SDK do Sandbox de privacidade do Android mais recente para ter a versão mais atualizada das APIs que preservam a privacidade.

2. Adicione o seguinte ao manifesto:

   • Permissão: inclua a permissão ACCESS_ADSERVICES_TOPICS para permitir que o app acesse a API Topics:

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

   • Configuração de serviços de publicidade: faça referência a um arquivo de configuração de serviços de publicidade no elemento <application> do 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>
     

3. Registre sua adtech com o Sandbox de privacidade para chamar a API Topics no SDK. Para testar localmente, é possível desativar a verificação de registro da API Topics com os seguintes comandos:

   adb shell setprop debug.adservices.disable_topics_enrollment_check true
   

4. Ative o acesso à API Topics. Por padrão, a API Topics fica desativada. Você precisa ativá-lo usando comandos ADB:

   adb shell device_config put adservices ppapi_app_signature_allow_list \"\*\"

   adb shell setprop debug.adservices.disable_topics_enrollment_check true

5. Comece a implementação bifurcando nossa versão Java ou Kotlin do app de exemplo para que você se familiarize com a recuperação de temas em um dispositivo.

Solicitar um conjunto de temas

A principal funcionalidade da API Topics fica no método getTopics() dentro do objeto TopicsManager, conforme mostrado neste exemplo:

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

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 OutcomeReceiver callback processa o resultado de forma assíncrona. Exemplo:

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

Quando sua configuração estiver pronta, faça uma chamada para receber uma GetTopicsResponse como resultado do método getTopics():

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

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

Esta invocação vai fornecer uma lista de objetos Topics que contêm valores de ID que correspondem aos tópicos na taxonomia de código aberto que são relevantes para a usuário ou um erro relevante. 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 de APIs do SDK Runtime e que preservam a privacidade no GitHub contém um conjunto de projetos individuais do Android Studio para ajudar você foi iniciado, incluindo exemplos que demonstram como inicializar e chamar a API Topics.

O cálculo dos temas é feito 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.

Detalhes de criptografia

Com a introdução da criptografia, as chamadas para GetTopics() agora vão gerar uma resposta com uma lista de objetos EncryptedTopic. A descriptografia desses resultados resultará em um objeto com o mesmo formato JSON do objeto Topic anterior.

A API Topics oferece suporte à implementação de HPKE (Criptografia de chave pública híbrida). Esperamos que o autor da chamada registrado hospede uma chave pública de 32 bits no endpoint de URL de criptografia pública fornecido durante a inscrição. Essas chaves precisam ser codificadas em Base64.

Os objetos EncryptedTopic têm três campos. A lista de temas retornados pode ser obtido usando a chave privada correspondente para a chave pública.

Para fins de desenvolvimento, é possível testar a criptografia da API Topics desativando a verificação de registro. Isso forçaria a API a usar a chave pública de teste para criptografar suas respostas. É possível descriptografar os temas criptografados usando o a chave privada correspondente.

Limitações

Para ver uma lista de recursos em desenvolvimento para a API Topics, consulte as notas da versão.

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.

Próximas etapas

Consulte também

Confira nossos recursos para entender melhor a API Topics no Android.

• Confira apps de exemplo, vídeos de collab e tutoriais da API Topics.
• Veja como usuários e desenvolvedores podem controlar a API.
• Confira os recursos de suporte para fazer perguntas, interagir e compartilhar feedback.