在 Kotlin Multiplatform SDK 中优化流程与付费墙的获取

在 Kotlin Multiplatform 中，可靠的流程或付费墙获取需要做到三件事：快速渲染、返回面向目标受众的实验变体，以及在网络较慢时优雅降级。以下规则涵盖了实现这些目标所需的时机、缓存与备用方案。

Tip

以下规则假设 Adapty.activate() 和 Adapty.identify() 已成功执行完毕。详情请参阅 Kotlin Multiplatform SDK 的调用顺序。

规则与注意事项

建议做法	避免做法	原因
仅获取即将展示的版位。	在启动时并发预取所有版位。	批量预取会阻塞主线程，导致启动时出现黑屏。
在归因数据有机会解析后再调用 `getFlow`——例如，在 `activate` 之后等待 1–2 秒，或在 `setOnProfileUpdatedListener` 触发后再调用。	在应用启动时立即调用 `getFlow`。	此时归因数据尚未落地，流程会基于默认目标受众进行解析，静默跳过市场细分和 ASA 个性化逻辑。
设置 `loadTimeout` 并为每个版位配置备用付费墙。	无限期等待 `getFlow` 返回。	若不设置超时，网络较差的用户将一直看到空白屏幕，直到网络恢复——或直接关闭应用。

请参阅获取付费墙和产品了解 fetchPolicy 和 loadTimeout 参数说明，以及版位了解如何选择合适的版位。

从应用包中加载首屏媒体

流程会从 Adapty 下载图片和视频。若想首屏媒体即时显示，可改为从应用包中加载。如果你已有原生用户引导的素材，这是复用现有资源的好方法。

在 Flow & Paywall Builder 中，为图片或视频设置自定义媒体 ID。上传的文件将作为备用资源。
将文件添加到应用资源目录 commonMain/composeResources/files/ 中。
创建 flow 视图时，在 customAssets 中为该 ID 传入已打包的文件：

// "welcome_video" is the custom media ID set in the Flow & Paywall Builder
val bundledAssets: Map<String, AdaptyCustomAsset> = mapOf(
    "welcome_video" to AdaptyCustomAsset.localVideoResource(
        path = Res.getUri("files/videos/welcome.mp4")
    ),
)

AdaptyUI.createFlowView(
    flow = flow,
    customAssets = bundledAssets,
).onSuccess { view ->
    view.present()
}.onError { error ->
    // handle the error
}

内置文件会增加应用的下载体积，因此只打包用户首屏看到的媒体资源。

未捆绑的媒体文件也会立即显示：流程布局中包含每张图片（包括视频静帧）的低分辨率缩略图，在完整文件加载完成前会先展示该缩略图。

完整的 customAssets 参考，请参阅自定义资源。

针对网络不佳环境的调优

适用于网络持续不稳定的市场（偏远地区、交通沿线、受路由问题影响的地区）：

除首次请求外，每次获取均设置 fetchPolicy = AdaptyPaywallFetchPolicy.ReturnCacheDataElseLoad。
在 Adapty 看板中为每个版位配置备用付费墙。
将 loadTimeout 设置为 3–5 秒，超时后接受备用付费墙。
不要让流程显示依赖 Adapty.getProfile() 的结果。独立调用 getFlow，避免因用户画像加载缓慢而阻塞 UI。