為 Android 設定 AdServices

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

注意： 您可以使用新的 Jetpack 程式庫整合隱私權防護機制 Sandbox 的隱私權保護 API (Topics、Protected Audience 和 歸因報表。您可以直接使用這個程式庫 Extension SDK 中的 Privacy Sandbox API 替代方案。

宣告 AdServices API 專屬權限

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

Attribution Reporting API：

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

Attribution Reporting API (含偵錯報表)：

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

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" />

視需要透過 Attribution Reporting 接收偵錯報表 API，請納入 AD_ID 權限：

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

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

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

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

設定 API 專屬廣告服務

與 PPAPI 存取權限類似，每個 API 在廣告服務設定中都有對應項目。這項設定可讓您 精確控管應用程式中由 API 管理的資源存取權，或 嵌入的 SDK

注意： 您不一定要設定特定廣告服務， 而且只有在應用程式開發人員想變更或限制存取權 因為系統會預設授予所有存取權

在資訊清單中指定 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) 中，請將 allowAllToAccess 屬性設為 true 授予任何呼叫者存取權。

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

注意：如要在最新的 AdServices SDK Extension 版本和開發人員預覽版中存取 Privacy Sandbox API，必須先完成註冊程序。

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

注意：由於已知的錯誤，在本機上測試時，應將 allowAllToAccess 設為 true。

以下範例說明如何指定廣泛存取權，以允許所有註冊 帳戶 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>

注意： 如果 Topics API 或 Protected Audience API 的註冊功能已停用 只要使用 ADB 指令，應用程式就能存取相關的 API ad-services-config 中指定的存取權控管。

宣告 Jetpack 程式庫依附元件

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

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

檢查 Ad Services Extensions 版本的可用性

如果您使用 ads-services 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 僅限於具有可見活動的應用程式，或 第 RunningAppProcessInfo 個，共 IMPORTANCE_FOREGROUND 個。