全屏广告的 activity 支持

注意： Privacy Sandbox on Android 是一个长期项目，本文档反映了其当前的设计。您的反馈对我们持续开发和增强其功能至关重要。

提供反馈

SDK 运行时对 SDK 启动新 activity 的方式施加了限制。这给全屏广告格式带来了挑战，因为这类广告格式通常依靠启动单独的 activity 来实现增强的控制和用户体验。为解决此问题，SDK 运行时为沙盒化 activity 引入了一种新机制。

在 SDK 运行时环境中加载的 SDK 无法直接在其清单中定义 <activity> 标记，也无法启动自己的 activity。 相反，引入了一项新的 intent 操作 START_SANDBOXED_ACTIVITY。

虽然 SDK 也受到限制，无法启动具有此操作的 intent，但 SDK 可以 请求客户端应用启动此 intent。然后，系统会创建一个平台定义的 activity，并将其传递给 SDK。此活动将在以下时间后开始 与 SDK 相同

然后，SDK 可以使用此 activity 植入和管理全屏广告 体验。

平台提供的 activity 是一个标准 android.app.Activity， 作为客户端应用任务的一部分启动。

注意：所提供的 activity (android.app.Activity) 对 SDK 端的一些 AndroidX 库（尤其是 Compose）的支持有限。

注意：此 activity 的 Context 不应直接由 SDK。相反，SDK 必须使用 SandboxedSdkProvider#getContext() 来获取 提供适当的情境。

在 SDK 运行时上创建 activity

创建 activity 的方法主要有两种：使用经过简化的 Jetpack Activity 库，或直接与平台 API 交互。

我们建议使用 activity 库，因为它们可通过抽象化底层的复杂性来简化 activity 创建过程。

activity 库

活动 库提供了 优点：

• 抽象化注册 activity 处理程序以及与客户端应用共享其标识符的内部详细信息。
• 通过允许应用开发者设置要满足的条件（谓词），使应用开发者能够更好地控制 SDK 在其应用内创建 activity 的方式。
• 为 SDK 创建一种统一的方式来定义启动 activity 的 API。

有三个 activity 库：核心库、客户端库和提供程序。

• core 库提供客户端应用和 提供程序库。
• provider 库为 SDK 提供用于启动 activity 的 API。
• client 库为客户端应用提供用于创建 activity 启动器的 API，SDK 可以使用该启动器请求应用启动 activity。

这些库引入了以下 API：

• SdkActivityLauncher：activity 启动器允许 SDK 处理从客户端应用启动的 activity。客户端应用应创建一个启动器，并将其作为参数传递给用于启动 activity 的 SDK API。
• <T : Activity & LifecycleOwner> T.createSdkActivityLauncher(() -> Boolean ): 客户端应用可从其 activity 调用以创建启动器的扩展函数。
• SdkActivityLauncher.launchSdkActivity(IBinder)：SDK 用于请求应用启动 activity 的方法。

使用 activity 库启动 activity 的流程如下：

1. SDK 会添加一个类型为 SdkActivityLauncher 附加到将启动 activity 的任何 API。
2. 客户端应用调用 createSdkActivityLauncher，以创建可在 API 调用时传递给 SDK 的启动器。
3. SDK 调用 SdkSandboxControllerCompat.registerSdkSandboxActivityHandler(SdkSandboxActivityHandlerCompat) 并检索标识符令牌。
4. SDK 调用 launchSdkActivity 启动 activity。

。

注意： 如果客户端应用想要添加条件以便 SDK 创建 activity，可以在创建启动器时传递谓词表达式。如果应用不想调节 activity 创建，它可以使谓词始终返回 true。

下图显示了使用 activity 库时的流程。

<ph type="x-smartling-placeholder">

</ph>

显示使用 activity 启动 activity 的流程的序列图 库

。

平台 API

该平台引入了以下 API，以方便创建和 SDK 运行时内沙盒化 activity 的管理：

• SdkSandboxActivityHandler: Activity 处理程序用于在创建 Activity 时通知 SDK，并且由 SDK 注册该处理程序。
• 为协助注册 activity 处理程序，SDK 可以使用 SdkSandboxController 下的以下方法：
  • .registerSdkSandboxActivityHandler(SdkSandboxActivityHandler): 注册 SdkSandboxActivityHandler， 该函数会返回 IBinder 标识符。
  • .unregisterSdkSandboxActivityHandler(SdkSandboxActivityHandler): 取消注册 SdkSandboxActivityHandler 使用其标识符
• SdkSandboxManager.startSdkSandboxActivity(Activity, IBinder): 从客户端应用调用的此方法会触发 SDK 的 activity 创建。客户端应用必须将它所选的启动 Activity 和 SDK 的 Activity 处理程序标识符作为参数传递。

如需使用平台 API 启动 activity，SDK 必须遵循以下流程：

1. SDK 会使用提供的 API 注册 activity 处理程序，并获取标识符。
2. SDK 与其客户端应用共享此标识符。
3. 客户端应用会调用方法，使用平台 API startSdkSandboxActivity(Activity, IBinder) 在 SDK 运行时内启动 activity，同时传递为此新 activity 选择的启动 activity 和 activity 处理程序的标识符。
4. 平台启动一个 activity，并通过 activity 处理程序 (SdkSandboxActivityHandler.onActivityCreated(Activity)) 中的回调通知 SDK。
5. SDK 根据该 activity 向其填充广告。

。

注意： onActivityCreated(Activity) 将通过 Activity.onCreate(Bundle), 在此阶段，SDK 应填充内容视图。

使用平台 API 会使 SDK 负责共享 SdkSandboxActivityHandler 的 标识符，以及 指导客户端应用如何使用它。

在以下流程图中，示例 SDK 包含一个 launchActivity(AppCallback) 方法，该方法需要 回调（在 SDK 的 API 中定义）。此回调供 SDK 共享 Activity 处理程序 (SdkSandboxActivityHandler) 的 标识符。

<ph type="x-smartling-placeholder">

</ph>

显示使用平台 API 启动 activity 的流程的序列图。

可见度

在 SDK 运行时内，集成到客户端应用的视图层次结构中的广告使用 侧面 渠道 将 SDK 视图从 SDK 进程呈现到客户端应用进程中。

SDK 无法使用与 SDK 运行时外部使用的相同 View API 来 判断用户是否能看到广告 附加到应用窗口 （可见度）。

相比之下，平台提供的 activity 以原生方式在 SDK 运行时进程内运行，这样便无需旁路，并且允许 SDK 使用标准 Android Activity 和 View API。

由于存在这些不同的实施方式，我们正致力于统一 来检索可见度信号，而不考虑广告加载情境。

Lifecycle

通过 ActivityHolder 传递给 SDK SdkSandboxActivityHandlerCompat.onActivityCreated(ActivityHolder) implements LifecycleOwner 并可用于了解 Lifecycle.Event。

返回导航

方法 ActivityHolder.getOnBackPressedDispatcher() 退货 OnBackPressedDispatcher 可用于注册 OnBackPressedCallback 实例处理返回导航。