設定 AdServices

詳閱 Android 版 Privacy Sandbox 說明文件時，請利用「開發人員預覽版」或「Beta 版」按鈕選取您要使用的計畫版本，因為兩者的操作說明可能不盡相同。

請按照以下操作說明宣告 API 專屬權限，並設定 SDK 對於目標 API 所管理資源的存取權。

宣告 AdServices API 專屬權限

您必須具備廣告服務 normal 權限，才能存取每個 PPAPI。在資訊清單中，請宣告應用程式或 SDK 所需 API 相應的適當存取權限。

Attribution Reporting API：

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

Protected Audience/Custom Audience API：

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

Topics API：

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

如果專案具有模組或 SDK 的依附元件，可能已在資訊清單檔案中宣告必要的廣告服務權限。根據預設，Gradle 建構作業會將所有資訊清單檔案合併為一個資訊清單檔案，並封裝到應用程式套件中。請透過「Merged Manifest」檢視畫面確認已使用正確的權限。

如果您需要避免透過 SDK 等依附元件將任何權限合併到應用程式，請為特定權限加入 remove 節點標記。以下範例說明如何避免合併 Topics 權限。

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

設定 API 專屬廣告服務

與 PPAPI 存取權限類似，每個 API 在廣告服務設定中都有對應項目。您可以使用這項設定，針對應用程式或內嵌 SDK 中受 API 管理的資源精細控管存取權。在資訊清單中指定 adservicesConfig 屬性，如以下範例所示：

<application ...>
      ...
    <property android:name="android.adservices.AD_SERVICES_CONFIG"
        android:resource="@xml/ad_services_config" />

      ...
</application>

指定資訊清單所參照的廣告服務 XML 資源，例如 res/xml/ad_services_config.xml。針對適用於您的應用程式 (或內嵌 SDK) 的每個隱私權保護 API，將 allowAllToAccess 屬性設定為 true，以向任何呼叫端授予存取權。

或者，您可以使用 allowAdPartnersToAccess 屬性，針對每項廣告技術授予精細的 API 存取權。必須提供透過註冊取得的開發人員註冊帳戶 ID 清單。如果 allowAllToAccess 屬性設定為 true，則此屬性的優先順序會高於 allowAdPartnersToAccess 屬性中指定的任何註冊帳戶 ID。

廣告技術平台也應確保其應用程式用戶端能正確授予廣告服務設定中必要隱私權保護 API 的存取權。

以下範例說明如何指定廣泛的存取權，以便讓任何註冊帳戶 ID 都能存取所有隱私權保護 API：

<ad-services-config>
   <!-- Attribution API -->
   <attribution allowAllToAccess="true" />

   <!-- Topics API -->
   <topics allowAllToAccess="true" />

   <!-- Protected Audience on Android API -->
   <custom-audiences allowAllToAccess="true" />
</ad-services-config>

以下範例說明如何針對特定註冊帳戶 ID，為每個隱私權保護 API 指定精細存取權：

<ad-services-config>
    <!-- Attribution API -->
    <attribution allowAdPartnersToAccess="ENROLLMENT-ID" allowAllToAccess="false" />

    <!-- Topics API →-->
    <includes-sdk-library name="ENROLLMENT-ID" />
    <topics allowAdPartnersToAccess="ENROLLMENT-ID" allowAllToAccess="false" />

    <!-- Protected Audience on Android API -->
    <custom-audiences allowAdPartnersToAccess="ENROLLMENT-ID" allowAllToAccess="false" />
</ad-services-config>

宣告 Jetpack 程式庫依附元件

使用 ads-adservices Jetpack 程式庫 1.0.0-beta01 以上版本，以整合 Privacy Sandbox 的隱私權保護 API。您可以使用這個程式庫，從平台層級詳細資訊中提取您的應用程式，並簡化與隱私權保護 API 的整合作業。

將 Maven 存放區新增至您的專案。
在應用程式或模組的 build.gradle 檔案中，宣告 ads-adservices Jetpack 程式庫依附元件。
使用來自 androidx.privacysandbox.ads.adservices.* 套件的 API。
ads-adservices Jetpack 程式庫提供內建 Kotlin 協同程式支援。您可能需要針對您的專案，整合適當的生命週期感知依附元件，以管理協同程式範圍。

檢查 Ad Services Extensions 版本的可用性

如果您使用廣告服務 Jetpack 程式庫來整合隱私權保護 API，則程式庫會檢查 obtain() 函式中要求的 API 是否可用。如果無法在裝置上取得要求的 API，此函式會傳回空值。以下範例說明如何初始化 Topics API 的 TopicsManager。運作方式類似存取其他隱私權保護 API。

Kotlin

import androidx.privacysandbox.ads.adservices.topics.TopicsManager

// The initialization function will return null if the requested
// functionality is not available on the device.
val topicsManager = TopicsManager.obtain(context)

Java

import androidx.privacysandbox.ads.adservices.topics.TopicsManager;

// The initialization function will return null if the requested
// functionality is not available on the device.
TopicsManager topicsManager = TopicsManager.obtain(context);

如果您在 Extension SDK 中直接使用 AdServices API，請查看包含所需 AdServices API 的 AdServices Extensions 版本。您可以在 API 參考資料中，找到特定 AdServices API 引入的版本。舉例來說，TopicsManager 類別的 API 參考資料會註明「Ad Services Extensions 4 的新功能」。請運用下列條件式檢查來驗證包含 AdServices API 的 SDK 擴充功能。

Kotlin

import android.os.ext.SdkExtensions

if (SDK_INT >= Build.VERSION_CODES.R && // The extensions API is available since R.
   SdkExtensions.getExtensionVersion(SdkExtensions.AD_SERVICES) >= 4) {

    // AdServices API is available.
...
}

Java

import android.os.ext.SdkExtensions;

if (SDK_INT >= Build.VERSION_CODES.R && // The extensions API is available since R.
   SdkExtensions.getExtensionVersion(SdkExtensions.AD_SERVICES) >= 4) {

    // AdServices API is available.
...
}

前景存取權限制

為提供資訊透明度，SDK 執行階段和隱私權保護 API 僅開放給具有可見 Activity (或 IMPORTANCE_FOREGROUND 設為 RunningAppProcessInfo) 的應用程式使用。