配置 AdServices

开发者预览版 Beta 版

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

---

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

声明 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。