配置适用于 Android 的 AdServices

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

注意 ：有一个新的 Jetpack 库支持与 Privacy 集成 沙盒可保护隐私的 API（Topics、Protected Audience 和 Attribution Reporting。您可以将此库用作 替代了 Extension SDK 中提供的 Privacy Sandbox API。

声明 AdServices API 专属权限

访问每个 PPAPI 都需要 AdServices 的 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 / 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，相应模块或 SDK 可能已在其清单文件中声明了所需的 AdServices 权限。默认情况下，Gradle 构建系统会将所有清单文件合并成一个清单文件打包到应用中。您可以使用合并后的清单视图确认使用了正确的权限。

如果需要阻止任何权限通过依赖项（例如 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 扩展版本和开发者预览版中访问 Privacy Sandbox API，您需完成注册进程。

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

注意：由于存在已知 bug，在本地进行测试时，您应将 allowAllToAccess 设置为 true。

以下示例展示了如何指定广泛访问权限以允许任何注册 对所有可保护隐私的 API 使用账号 ID 的访问权限：

<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 停用了注册功能 应用能够访问相关 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 协程支持。您可能需要添加适合您项目的恰当生命周期感知型依赖项来管理协程范围。

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

如果您使用广告服务 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 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 的应用，或具有 第 RunningAppProcessInfo 行，共 IMPORTANCE_FOREGROUND 行。