配置适用于 Android 的 AdServices

请按照以下说明声明 API 专属权限，并配置对目标 API 管理的资源的 SDK 访问权限。

注意 ：有新的 Jetpack 库支持与 Privacy Sandbox 的隐私保护 API（Topics、Protected Audience 和 Attribution Reporting）集成。您可以使用此库来直接替代 Extension SDK 中提供的 Privacy Sandbox API。

声明 AdServices API 专属权限

访问每个 PPAPI 都需要广告服务 normal 权限。在清单中，声明与您的应用或 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 / 自定义受众群体 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，那么这些模块或 SDK 可能已在其清单文件中声明了所需的广告服务权限。默认情况下，Gradle build 会将所有清单文件合并到打包到应用中的单个清单文件中。使用 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。

注意 ：如需在最新的 AdServices SDK 扩展版本和开发者预览版中访问 Privacy Sandbox API，您需要完成注册流程。

广告技术平台还应确保其应用客户端在广告服务配置中正确地授权访问可保护隐私的所需 API。

注意 ：由于存在已知 bug，在本地测试时，您应将 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>

注意： 如果使用 adb 命令停用了 Topics API 或 Protected Audience API 的注册功能，则无论 ad-services-config 中指定的访问权限控制如何，应用都可以访问相关 API。

声明 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 协程支持。您可能需要加入适合您项目的相应生命周期感知型依赖项来管理协程范围。

检查广告服务扩展版本的可用性

如果您使用广告服务 Jetpack 库与可保护隐私的 API 集成，该库会在 obtain() 函数中检查请求的 API 是否可用。如果请求的 API 在设备上不可用，该函数会返回 null。以下示例说明了如何为 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 扩展版本。在 API 参考文档中，您可以标识引入了特定 AdServices API 的版本。例如，TopicsManager 类的 API 参考文档指明它是“在广告服务扩展 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.
...
}

前台使用权限制

为了做到公开透明，仅限具有可见 activity 或 RunningAppProcessInfo 为 IMPORTANCE_FOREGROUND 的应用访问 SDK 运行时和可保护隐私的 API。