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