请按照以下说明声明 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。
广告技术平台还应确保其应用客户端在广告服务配置中正确地授权访问可保护隐私的所需 API。
以下示例展示了如何指定广泛访问权限,以允许任何注册账号 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>
声明 Jetpack 库依赖项
使用 ads-adservices Jetpack 库 1.0.0-beta01 或更高版本可集成 Privacy Sandbox 的隐私保护 API。您可以使用此库从平台级详细信息中提取应用,并简化与隐私保护 API 的集成。
- 将 Maven 制品库添加到您的项目中。
- 在应用或模块的
build.gradle
文件中声明 ads-adservices Jetpack 库依赖项。 - 使用
androidx.privacysandbox.ads.adservices.*
软件包中的 API。 - 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.
...
}
前台使用权限制
为了做到公开透明,仅限具有可见 activity 或 RunningAppProcessInfo
为 IMPORTANCE_FOREGROUND
的应用访问 SDK 运行时和可保护隐私的 API。