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

为了保护用户隐私，所有 Android 应用都应使用用户可重置的标识符。其中一个标识符是广告 ID，它以唯一的方式标识特定用户，用于广告用例（例如广告个性化）。

为了支持在运行您的应用的设备之间实现标准化的广告跟踪解决方案，您可以使用 广告 ID 库。此库适用于运行 Android 4.0（API 级别 14）及更高版本的设备，它定义了一个与系统级广告提供商交互的界面。此界面允许您的应用接收一致的广告 ID 值。

包含在广告 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 库架构

Architecture diagram
图 1. 广告 ID 库架构

图 1 描述了广告 ID 库的结构。该库包含以下模块。

  • 一个客户端模块，它是包含在应用中的一个精简层。

  • 一个由设备制造商提供的提供程序模块。此模块的实现必须定义一个设置 UI，以便用户能够重置其广告 ID 并切换广告跟踪首选项。

客户端模块与提供程序模块通信以检索广告 ID 和用户关于广告跟踪的首选项。

库如何处理多个提供程序

设备可能同时支持多个系统级广告提供程序。如果广告 ID 库检测到这种情况，它将确保您的应用始终从同一个提供程序检索信息，前提是该提供程序仍然可用。此过程可保持广告 ID 的一致性。

如果可用广告提供程序集随着时间的推移而发生变化，并且您的应用与不同的广告标识符提供程序进行交互，则所有其他客户端应用也将开始使用该新提供程序。您的应用将演示与用户请求重置其广告 ID 时相同的效果。

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

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