Receber um código de publicidade que pode ser redefinido pelo usuário

Para proteger a privacidade do usuário, é uma prática recomendada que todos os apps para Android funcionem com identificadores redefiníveis pelo usuário. Um desses identificadores é o código de publicidade, que identifica exclusivamente um usuário específico para casos de uso de publicidade, como personalização de anúncios.

Para oferecer uma solução padronizada de rastreamento de anúncios nos dispositivos que executam seu app, você pode usar a biblioteca Advertising ID, que faz parte do Jetpack. Essa biblioteca, disponível em dispositivos com o Android 4.0 (API nível 14) e posterior, define uma interface para interagir com provedores de anúncios no nível do sistema. Essa interface permite que o app receba valores consistentes de código de publicidade.

O provedor de anúncios incluído na biblioteca Advertising ID também define um intent padrão para abrir uma tela de configurações implementada por ele. Essa tela de configurações permite ao usuário redefinir o código de publicidade e desativar a personalização de anúncios.

Este guia explica como usar o módulo do cliente da biblioteca Advertising ID para receber um código de publicidade consistente por usuário do dispositivo. Ele também apresenta uma visão geral da arquitetura da biblioteca.

Configurar o app de cliente

Interagindo com o módulo de cliente da biblioteca Advertising ID, seu app pode recuperar um código de publicidade consistente que representa o usuário que está interagindo com o app.

O código de publicidade é representado pela versão 3 do formato de identificador universal exclusivo (UUID, na sigla em inglês) ou de um formato equivalente de 128 bits:

    38400000-8cf0-11bd-b23e-10b96e40000d

A biblioteca Advertising ID normaliza o valor de retorno conforme necessário para oferecer códigos usando esse formato.

Para recuperar o código de publicidade redefinível pelo usuário para seu app, complete estas etapas:

  1. Verifique se um provedor de anúncios está disponível chamando AdvertisingIdClient.isAdvertisingIdProviderAvailable(). Se esse método retornar false, seu app deverá usar outros meios para realizar qualquer caso de uso de rastreamento de anúncios necessário.

  2. Veja os detalhes do identificador do anúncio, inclusive o código de publicidade, chamando AdvertisingIdClient.getAdvertisingIdInfo(). A biblioteca Advertising ID executa esse método na linha de execução de um worker e usa um tempo limite de conexão de 10 segundos.

O seguinte snippet de código demonstra como recuperar o código de publicidade, junto com outras informações do provedor de anúncios:

app/build.gradle

    dependencies {
      implementation 'androidx.ads:ads-identifier:1.0.0-alpha01'

      // Used for the calls to addCallback() in the snippets on this page.
      implementation 'com.google.guava:guava:28.0-android'
    }

MyAdIdClient

Kotlin

    // Used for the call to addCallback() within this snippet.
    import com.google.common.util.concurrent.Futures.addCallback

    private fun determineAdvertisingInfo() {
        if (AdvertisingIdClient.isAdvertisingIdProviderAvailable()) {
            val advertisingIdInfoListenableFuture =
                    AdvertisingIdClient.getAdvertisingIdInfo(applicationContext)

            addCallback(advertisingIdInfoListenableFuture,
                    object : FutureCallback<AdvertisingIdInfo> {
                override fun onSuccess(adInfo: AdvertisingIdInfo?) {
                    val id: String = adInfo?.id
                    val providerPackageName: String = adInfo?.providerPackageName
                    val isLimitTrackingEnabled: Boolean =
                                    adInfo?.isLimitTrackingEnabled
                }

                override fun onFailure(t: Throwable) {
                    Log.e("MY_APP_TAG",
                            "Failed to connect to Advertising ID provider.")
                    // Try to connect to the Advertising ID provider again, or fall
                    // back to an ads solution that doesn't require using the
                    // Advertising ID library.
                }
            }, Executors.newSingleThreadExecutor())
        } else {
            // The Advertising ID client library is unavailable. Use a different
            // library to perform any required ads use cases.
        }
    }

Java

    // Used for the call to addCallback() within this snippet.
    import com.google.common.util.concurrent.Futures;

    private void determineAdvertisingInfo() {
        if (AdvertisingIdClient.isAdvertisingIdProviderAvailable()) {
            ListenableFuture<AdvertisingIdInfo> advertisingIdInfoListenableFuture =
                    AdvertisingIdClient.getAdvertisingIdInfo(getApplicationContext());
            Futures.addCallback(advertisingIdInfoListenableFuture,
                    new FutureCallback<AdvertisingIdInfo>() {
                        @Override
                        public void onSuccess(AdvertisingIdInfo adInfo) {
                            String id = adInfo.getId();
                            String providerPackageName =
                                    adInfo.getProviderPackageName();
                            boolean isLimitTrackingEnabled =
                                    adInfo.isLimitTrackingEnabled();

                        // Any exceptions thrown by getAdvertisingIdInfo()
                        // cause this method to get called.
                        @Override
                        public void onFailure(Throwable throwable) {
                            Log.e("MY_APP_TAG",
                                    "Failed to connect to Advertising ID provider.");
                            // Try to connect to the Advertising ID provider again,
                            // or fall back to an ads solution that doesn't require
                            // using the Advertising ID library.
                        }
                    });
        } else {
            // The Advertising ID client library is unavailable. Use a different
            // library to perform any required ads use cases.
        }
    }

Arquitetura da biblioteca Advertising ID

Diagrama da arquitetura
Figure 1. Arquitetura da biblioteca Advertising ID

O diagrama mostrado na Figura 1 ilustra como a biblioteca Advertising ID está estruturada. A biblioteca consiste nos seguintes módulos:

  • Um módulo de cliente, que é uma camada fina incluída nos apps.
  • Um módulo de provedor, que o fabricante do dispositivo disponibiliza. As implementações desse módulo precisam definir uma IU de configurações para oferecer aos usuários a capacidade de redefinir o código de publicidade e alternar as preferências de rastreamento de anúncios.

O módulo de cliente se comunica com o módulo de provedor para recuperar códigos de publicidade e preferências do usuário em relação ao rastreamento de anúncios.

Como a biblioteca lida com vários provedores

É possível que um dispositivo seja compatível com vários provedores de anúncios ao mesmo tempo no sistema. Se a biblioteca Advertising ID detectar essa situação, ela garantirá que seu app sempre recupere informações do mesmo provedor, presumindo que ele permaneça disponível. Esse processo mantém o código de publicidade consistente.

Se o conjunto de provedores de anúncios disponíveis mudar ao longo do tempo, de modo que seu app interaja com um provedor de identificador de anúncio diferente, todos os outros apps de cliente também começarão a usar esse novo provedor. Seu app demonstra o mesmo comportamento que ocorreria se o usuário solicitasse a redefinição do código de publicidade.

A biblioteca de provedor Advertising ID usa a seguinte ordem determinística para classificar os provedores:

  1. Provedores que solicitaram a permissão androidx.ads.identifier.provider.HIGH_PRIORITY.
  2. Provedores instalados no dispositivo há mais tempo.
  3. Provedores que aparecem primeiro em ordem alfabética.