在 Capacitor SDK 中优化流程和付费墙的获取

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

Tip

以下规则假设 adapty.activate() 和 adapty.identify() 已完成调用。详见 Capacitor SDK 调用顺序。

规则与注意事项

应该这样做	不要这样做	原因
只获取即将展示的版位。	在启动时并发预取所有版位。	批量预取会阻塞主线程，并在请求高峰期出现黑屏。
在归因有机会完成解析之后再调用 `getFlow`——例如，在 `activate` 之后等待 1–2 秒，或等 `onLatestProfileLoad` 监听器触发后再调用。	在 `App.tsx` 的应用启动阶段调用 `getFlow`。	此时归因数据尚未就绪，流程会以默认目标受众进行解析，从而悄悄跳过市场细分和 ASA 个性化设置。
设置 `loadTimeoutMs`，并为每个版位配置备用付费墙。	无限等待 `getFlow` 返回。	如果没有超时限制，网络状况较差的用户会一直看到空白屏幕，直到网络恢复——或者直接关掉应用。

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

从应用包中显示首屏媒体内容

流程会从 Adapty 下载图片和视频。若想让首屏媒体内容立即显示，可以改为从应用包中提供。这是复用已有资源的好方法，例如现有原生用户引导中的视觉素材。

在流程和付费墙编辑工具中，为图片或视频设置自定义媒体 ID。上传的文件将作为备用资源。
将文件添加到原生项目中：iOS 应用包和 Android assets 文件夹。
创建流程视图时，在 customAssets 中为该 ID 传入对应的本地文件：


// "welcome_video" is the custom media ID set in the Flow & Paywall Builder
const bundledAssets: Record<string, AdaptyCustomAsset> = {
  'welcome_video': {
    type: 'video',
    fileLocation: {
      ios: { fileName: 'welcome.mp4' },
      android: { relativeAssetPath: 'videos/welcome.mp4' },
    },
  },
};

const view = await createFlowView(flow, { customAssets: bundledAssets });

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

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

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

针对网络连接较差的环境进行调优

对于网络连接长期不稳定的市场（农村地区、公共交通途中、受路由影响的地区）：

除首次请求外，所有请求均设置 fetchPolicy: 'return_cache_data_else_load'。
在 Adapty 看板中为每个版位配置备用付费墙。
将 loadTimeoutMs 设置为 3000–5000 毫秒，并在超时触发时接受备用付费墙。
不要将流程显示与 adapty.getProfile() 绑定。独立调用 getFlow，避免因用户画像加载缓慢而阻塞 UI。