取得可由使用者重設的廣告 ID Android Jetpack 的一部分。

為保護使用者隱私，所有 Android 應用程式的最佳做法是使用可由使用者重設的 ID。其中一種 ID 是廣告 ID，可明確識別特定使用者，用於廣告用途，例如廣告個人化。

如要支援在執行應用程式的裝置上使用標準化廣告追蹤解決方案，請使用廣告 ID 程式庫。這個程式庫適用於搭載 Android 4.0 (API 級別 14) 以上版本的裝置，可定義與系統層級廣告技術供應商互動的介面。這個介面可讓您的應用程式接收一致的廣告 ID 值。

廣告 ID 程式庫隨附的廣告供應商也會定義標準意圖，用於開啟廣告供應商實作的設定畫面。使用者可以在這個設定畫面重設廣告 ID，並停用廣告個人化功能。

本指南說明如何使用 Advertising 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 詳細資料。廣告 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 程式庫架構

廣告 ID 程式庫架構。
圖 1. 廣告 ID 程式庫架構

圖 1 顯示 Advertising ID 程式庫的結構。程式庫包含下列模組：

  • 用戶端模組：應用程式內含的精簡層。
  • 裝置製造商提供的供應商模組。這個模組的實作項目必須定義設定使用者介面，讓使用者能夠重設廣告 ID，以及切換廣告追蹤偏好設定。

用戶端模組會與供應商模組通訊，以擷取廣告 ID 和使用者對廣告追蹤的偏好設定。

程式庫如何處理多個供應商

裝置可以同時支援多個系統層級的廣告供應商。如果廣告 ID 程式庫偵測到這種情況，會驗證應用程式是否一律從同一供應商擷取資訊 (假設該供應商仍可提供服務)。這項程序可確保廣告 ID 一致。

如果可用的廣告供應商組合隨時間變更，且您的應用程式與不同的廣告 ID 供應商互動，所有其他用戶端應用程式也會開始使用該新供應商。您的應用程式會出現與使用者要求重設廣告 ID 時相同的行為。

廣告 ID 供應商程式庫會使用下列確定性順序，為供應商排名：

  1. 已要求 androidx.ads.identifier.provider.HIGH_PRIORITY 權限的供應商。
  2. 在裝置上安裝時間最長的供應商。
  3. 按字母順序排列時，排在最前面的供應商。