為 Android 設定 AdServices

請按照以下操作說明宣告 API 專屬權限，並設定 SDK 對於目標 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。

廣告技術平台也應確保應用程式用戶端正確授予授權 存取廣告服務設定中必要的隱私權保護 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

  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 個。