SDK 运行时 API:集成指南

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


为帮助您制定集成计划,本指南全面介绍了集成过程,其中可能包括 Privacy Sandbox on Android 开发者预览版当前阶段尚未实现的功能。对于此类情况,我们提供了时间表指导。

下图显示了更新后的 SDK 运行时集成开发工作流。列于同一列中的几部分可以并行处理;例如,可以在设置测试环境的同时完成合作伙伴互动。

SDK 运行时集成工作流的直观示意图。
图 1:SDK 运行时集成工作流。

前提条件和设置

完成此前期准备工作可确保您充分理解 SDK 运行时,并能够在广告技术生态系统中使用 API 实现有意义的结果。

熟悉该 API

首先阅读设计方案,熟悉 SDK 运行时及其功能和限制。

阅读开发者指南,了解如何将您的用例需要的代码和 API 调用纳为己用。

提交您对本文档的反馈,尤其是与待解决问题相关的反馈。

注册以接收关于 Privacy Sandbox on Android 的最新动态。这可以帮助您及时了解未来版本中引入的新功能。

设置并测试示例应用

准备好开始集成后,请按照此处的说明,在 Android Studio 中下载最新的开发者预览版。本指南需要使用最新 Canary 版的 Android Studio。您可以并行使用此版本的 Android Studio 和您使用的其他版本,如果您无法满足此要求,请告知我们

对我们的示例应用中的代码进行复刻并运行代码,以便熟悉如何在设备或模拟器上安装名为“example-sdk”的 RE SDK 以及名为“client-app”的客户端应用,以确保可以加载示例广告。

调整现有 SDK 以支持 SDK 运行时

本部分的目标是在支持运行时的 SDK (RE SDK) 现有 SDK 中实现展示横幅广告等功能,并设置应用与 RE SDK 之间的通信。

  • 创建或更新 sdk-example 和 sdk-implementation,以便在 RE SDK 中实现功能。

  • 在架构上,不妨考虑将 RE SDK 作为依赖项添加到现有 SDK(充当封装容器)。这样一来,客户端应用就可以直接调用现有的 SDK 或封装容器。封装容器 SDK 可能会根据如下所述的不同策略路由 API 调用。

SDK 运行时集成后的系统架构直观示意图。
图 2:SDK 运行时集成后的系统架构。

对于需要自定义数据的用例(例如调用 PPAPI),需要使用 IPC 创建 API 定义。使用 Android 的 IBinder 和 AIDL 创建通信协议,以将信息发送到支持运行时的 SDK,以便获取任何必要的信息或执行任何必要的操作。如需详细了解 SDK 运行时开发者指南,请点击此处

将流量路由到支持运行时的 SDK

API 调用的路由策略

根据您的用例,建议通过现有 SDK 和 RE SDK 代码路径路由 SDK 调用。这将有助于您在首次部署时实现 A/B 测试。为了简化应用集成,本指南将考虑以下场景:应用将依赖 RE SDK 并会适时将其委托给现有 SDK。考虑以下策略:

将一定比例的 SDK 调用路由到 RE SDK

仅将一定比例的 SDK 调用路由到 RE SDK。将其余代码路由到现有的 SDK 代码路径。例如,如果您需要满足 SDK 请求一次(例如展示横幅广告),请考虑使用此策略。

  • 修改现有 SDK 以将一定比例的请求路由到 RE SDK。 例如,使用基于服务器的动态配置标志(如 Firebase Remote Config)来动态控制分流标准。
  • 这实质上是将现有 SDK 作为应用与之互动的唯一接口,并负责将 SDK 请求路由到新的 RE SDK。
  • 您的代码应仅重定向可由 RE SDK 处理的请求。例如,验证 SDK 运行时是否支持相应广告格式。
  • 请按照这些说明更新您的 SDK 代码,以便与 RE SDK 进行交互。

路由逻辑的伪代码:

void showAd(AdRequest request) {
  if (request.isBannerAd() && enableRuntimeSdkDiversion() == true) {
    // Call showAd() from the RE SDK
  } else {
    // Call showAd() using the existing SDK code path
  }
}

将所有 SDK 调用同时路由到现有 SDK 和 RE SDK

在支持的设备上,将所有 SDK 调用同时路由到现有的 SDK 代码路径和 RE SDK 代码路径。当您出于比较目的而需要同时测试现有代码路径和新代码路径时,请考虑使用此策略。例如,比较转化报告结果。

  • 修改代码以将所有 SDK 调用同时路由到现有的 SDK 代码路径和 RE SDK 代码路径。您应验证 SDK 运行时是否支持相应功能,以及是否已成功加载 RE SDK。

路由逻辑的伪代码:

void reportAttribution(AdRequest request) {
  if (request.isFeatureSupported() && isSdkLoaded() == true) {
    // Call RE SDK
  }

  // Call existing SDK code path
}

适用于支持运行时的 SDK 分发的封闭式 Beta 版测试

Google Play 将为已注册加入 Beta 版计划并执行本地测试的开发者提供与广告相关的 SDK 的封闭式 Beta 版计划。如果您有兴趣参与,请在此处注册。