适用于 Android 的 Privacy Sandbox 问题排查指南

本文档介绍了如何解决设置 Privacy Sandbox on Android 时的常见问题。如果您发现本指南中未提及的错误,请告知我们

有些错误可能会因多种原因而被抛出。下面列出了一些较常见的错误及其修复方法,但相同的错误消息也可能由不同的原因导致。

排查问题之前的准备工作

停用设备配置更新

在排查 Privacy Sandbox 测试中遇到的任何问题时,首先要做的应该是停用设备配置更新。这可确保您的设备不会从服务器提取更新后的配置,也不会无意中停用测试设备上的 Privacy Sandbox。

使用以下命令停用设备配置更新:

adb shell device_config set_sync_disabled_for_tests persistent

如果您想在测试后重新启用设备配置更新,可以使用以下命令:

adb shell device_config set_sync_disabled_for_tests none

启用 adservices 详细日志记录功能

adservices 中的详细日志记录功能可针对您遇到的错误提供更多背景信息。如要启用此功能,请使用以下命令:

adb shell setprop log.tag.adservices VERBOSE

确保您的设备已正确配置

如果您刚刚停用了设备配置更新,我们建议您再次执行这些步骤,以确保您的设备配置正确并在测试期间保持配置不变。

  • 使用适用的 adb 命令启用 PPAPI。
  • 注册设备或停用注册(具体取决于您的目标)。

检查代码以确保 PPAPI 可用

您可以在代码库中添加检查项,以确保您的设备安装了 Privacy Sandbox 所需的正确版本。

如果您通过 SDK 扩展使用 Beta 版,请检查 build 和 SDK 扩展的版本是否正确:

如果您通过 Jetpack 库使用 Beta 版,并且 Privacy Sandbox 在您的设备上不可用,初始化函数会返回 null。例如:

无论哪种版本,均须检查 Google Play 服务:

安全异常

如果某项内容无权访问 Privacy Sandbox 资源,通常会导致安全异常错误。

未请求权限

错误

Failed to get Ad ID: java.lang.SecurityException: Caller is not authorized to call this API. Permission was not requested

可能的原因

您必须声明对广告 ID 的访问权限。

修复方法

AndroidManifest.xml 中声明权限:

<uses-permission android:name="android.permission.ACCESS_ADSERVICES_AD_ID" />

调用方未获授权

错误

Failed to find resolveInfo for adServices service. Intent action: android.adservices.adid.AdIdProviderService

Failed to find AdServices services

Caller not authorized

可能的原因

您未正确注册设备。确保您已按照所有注册说明(包括注册后的步骤)配置了设备。

可能的原因

注册网址不匹配。

修复方法

  1. 查看您的注册数据,检查您在代码中使用的网址与在 Privacy Sandbox 中注册的网址之间是否存在不一致的情况。例如,您可能使用的是 https://adtech.example.com/source,但注册的网址却是 https://adtech.example.com/register_source
  2. 请调整您的代码,使其与注册的网址匹配。例如,您可以调整此示例应用中的相应行,将“/register_source”而不是“/source”附加到网址。

如果此错误仍然存在

您的公司可能不在注册列表中,或者公司已注册,但不在应用清单的许可名单中。请与 android-ps-support@google.com 联系,确保贵组织已在 Privacy Sandbox 中注册。

调用方未获允许

错误

Failed to get Ad ID: java.lang.SecurityException: Caller is not authorized to call this API. Caller is not allowed. Package [package name] is not allowed to call the API

可能的原因

软件包名称不在许可名单中。

修复方法

将所有软件包名称列入许可名单:

如果您直接使用 adb shell

先前列出的命令适用于 Bash 和其他 shell,但如果您直接启动 adb shell 并尝试运行这些命令,则不应对引号进行转义。请改为运行以下命令:

修复方法

将您的软件包名称添加到许可名单:

adb shell device_config put adservices ppapi_app_allow_list [package name]

验证您的软件包名称是否在许可名单中:

adb shell device_config get adservices ppapi_app_allow_list

如果需要,您可以使用以下命令删除许可名单:

adb shell device_config delete adservices ppapi_app_allow_list

非法状态异常

非法状态异常表示系统在非法或不恰当的时间调用了某个方法,此时环境或应用所处的状态不适合执行请求的操作。

非法状态异常:服务不可用

错误

com.example.measurement.sampleapp E Failed binding to measurement service: java.lang.IllegalStateException: Service is not available

可能的原因

必须停用终止开关。

修复方法

您可以使用以下命令停用终止开关:

adb shell 'device_config put adservices global_kill_switch false'

可能的原因

未征得用户同意。

修复方法

您可以运行以下命令:

adb shell am start -n com.google.android.adservices.api/com.android.adservices.ui.settings.activities.AdServicesSettingsMainActivity

上述命令运行完毕后,将“启用 Privacy Sandbox”偏好设置切换为“开启”状态。

adb 命令错误

找不到相应作业

错误

Could not find job 14 in package com.google.android.adservices.api/ user 0

可能的原因

Privacy Sandbox API 尚未触发。

修复方法:在运行此作业之前,请调用其中一个 Privacy Sandbox API,例如 registerSource()getTopics()selectAds()。此调用预计将失败,但系统需要此调用才能激活该 API。然后,重新运行 jobscheduler 14 命令。

可能的原因

Google Play 商店需要更新。

修复方法

  1. 使用您的 Google 账号登录设备或模拟器。
  2. 依次访问 Google Play 商店 > 个人资料图标 > 设置 > 关于。在 Play 商店版本标题下,点按更新 Play 商店

提交工单

如果上述步骤未能解决您的错误,请提交工单并提供以下信息:

  1. 您使用的是哪个发布版本,开发者预览版还是 Beta 版?您使用的是哪个版本?您可以在设置 > 关于手机 > build 号下找到版本代码。
  2. 如果您使用的是 Beta 版,请运行 adb shell getprop | grep build.version.extensions 并在工单中附上运行结果。
  3. 您的设备安装的是哪个版本的 Google Play 服务?请运行 adb shell dumpsys package com.google.android.gms | grep versionName 并在工单中附上该命令的运行结果。
  4. 请附上完整的 bug 报告。如需获取完整的 bug 报告,请运行 adb bugreport,或 按照说明操作。