配置 AdServices

开发者预览版 Beta 版

在阅读 Privacy Sandbox on Android 文档时，请使用开发者预览版或 Beta 版按钮选择您所使用的程序版本，因为说明可能会有所不同。

---

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

声明 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 在广告服务配置中都有一个相应条目。此配置可以让您对应用或嵌入式 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。