获取用户可重置的广告 ID Android Jetpack 的一部分。

为了保护用户隐私,所有 Android 应用都应该使用用户可重置的标识符。其中一个标识符就是广告 ID,它针对广告用例(例如广告个性化)唯一标识特定用户。

如需在运行您应用的各种设备上支持标准化的广告跟踪解决方案,您可以使用广告 ID 库。此库(适用于搭载 Android 4.0(API 级别 14)及更高版本的设备)定义了一个与系统级广告提供程序互动的接口。此接口可让您的应用接收一致的广告 ID 值。

广告 ID 库随附的广告提供程序还定义了一个标准 intent,用于打开广告提供程序实现的设置屏幕。用户可以通过此设置屏幕重置其广告 ID 以及选择停用广告个性化功能。

本指南介绍了如何使用广告 ID 库的客户端模块为每个设备用户获取一致的广告 ID。然后,本指南简要介绍该库的架构。

配置客户端应用

通过与广告 ID 库的客户端模块互动,您的应用可以检索一致的广告 ID,该 ID 代表正在与应用互动的用户。

广告 ID 使用版本 3 的通用唯一标识符 (UUID) 格式或等效的 128 位格式表示:

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

广告 ID 库会根据需要对返回值进行标准化,以提供使用此格式的 ID。

如需为您的应用检索用户可重置的广告 ID,请完成以下步骤:

  1. 通过调用 AdvertisingIdClient.isAdvertisingIdProviderAvailable() 检查广告提供程序是否可用。如果此方法返回 false,您的应用应使用其他方式来执行任何必要的广告跟踪用例。

  2. 通过调用 AdvertisingIdClient.getAdvertisingIdInfo() 获取广告标识符的详细信息,包括广告 ID。广告 ID 库在工作线程上执行此方法,并使用 10 秒的连接超时。

以下代码段演示了如何从广告提供程序检索广告 ID 以及其他信息:

app/build.gradle

Groovy

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'
}

Kotlin

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
            }

            // Any exceptions thrown by getAdvertisingIdInfo()
            // cause this method to be called.
            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 ad 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 ad 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 be 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 ad 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 ad use cases.
    }
}

广告 ID 库架构

架构示意图
图 1. 广告 ID 库架构

图 1 说明了广告 ID 库的结构。 该库包含以下模块:

  • 客户端模块,它是应用中包含的一个薄层。
  • 提供程序模块,由设备制造商提供。此模块的实现必须定义设置界面,以便用户能够重置其广告 ID 和切换广告跟踪偏好设置。

客户端模块与提供程序模块进行通信,以检索广告 ID 以及有关广告跟踪的用户偏好设置。

广告 ID 库如何处理多个提供程序

设备可以同时支持多个系统级广告提供程序。如果广告 ID 库检测到这种情况,它会确保您的应用始终从同一提供程序检索信息(假定该提供程序仍然可用)。此过程可让广告 ID 保持一致。

如果可用的广告提供程序集合随着时间的推移而发生变化,并且您的应用与其他广告标识符提供程序交互,则所有其他客户端应用也会开始使用这一新提供程序。您的应用将表现出与用户请求重置广告 ID 时相同的行为。

广告 ID 提供程序库使用以下确定顺序对提供程序进行排序:

  1. 已请求 androidx.ads.identifier.provider.HIGH_PRIORITY 权限的提供程序。
  2. 在设备上安装时间最长的提供程序。
  3. 按字母顺序最先显示的提供程序。