获取流程与付费墙 - React Native

在设计好流程之后，您可以在移动应用中展示它。第一步是获取与版位关联的流程或付费墙及其视图配置，具体方法如下所述。

请注意，本主题涉及在 Adapty 编辑工具中设计的流程和付费墙。如果您是手动实现付费墙，请参阅在移动应用中获取远程配置付费墙的付费墙和产品主题。

开始之前

您需要：

• Adapty 看板中的产品：创建您的产品。
• 包含产品的流程：在流程与付费墙编辑工具中构建，并为其分配产品。
• 版位：创建版位并将您的流程分配给它。
• 已安装 Adapty SDK：请参阅 React Native SDK 安装指南。

获取流程/付费墙

如果你已在编辑工具中设计好了流程或付费墙，则无需在移动端代码中手动处理其渲染逻辑来向用户展示。此类流程或付费墙本身已包含展示内容和展示方式的全部信息。不过，你仍需通过版位获取其 ID 和视图配置，然后在移动应用中将其呈现出来。

尽早获取流程或付费墙并创建其视图 — 最好在展示之前提前完成。createFlowView 方法会加载视图配置，并在后台开始下载和缓存图片。调用越早，这些下载就有越充裕的时间完成。等到真正展示流程或付费墙时，其配置和图片可能已经缓存完毕，随时可以显示。

要获取流程或付费墙，请使用 getFlow 方法：

try {
    const placementId = 'YOUR_PLACEMENT_ID';

    const flow = await adapty.getFlow(placementId);
  // the requested flow/paywall
} catch (error) {
    // handle the error
}

参数：

参数	是否必需	描述
placementId	必填	目标版位的标识符。这是您在 Adapty 看板中创建版位时所指定的值。
fetchPolicy	默认值：'reload_revalidating_cache_data'	fetchPolicy 决定 SDK 优先从哪一层读取数据，而非是否可以使用缓存。默认情况下，SDK 会优先请求服务器，若请求失败则返回缓存数据。我们推荐此方式，因为它能确保用户始终获取最新数据。 但如果您认为用户的网络环境不稳定，可以考虑使用 'return_cache_data_else_load'，该策略顺序相反——优先读取缓存，仅在无缓存时才请求服务器。用户获取的数据可能不是最新的，但无论网络状况如何，都能获得更快的加载速度。缓存会定期更新，因此在会话期间使用缓存以减少网络请求是安全的。 第三种策略 'return_cache_data_if_not_expired_else_load' 介于两者之间：当缓存数据的存活时间小于您传入的 maxAgeSeconds 时，优先读取缓存；超过该时间后则请求服务器。 请注意，缓存在应用重启后依然保留，仅在应用重新安装或手动清除时才会被清空。 Adapty SDK 将付费墙数据本地存储于两层中：上述定期更新的缓存层，以及备用付费墙层。我们还使用 CDN 加快付费墙的加载速度，并设有独立的备用服务器以应对 CDN 不可达的情况。该系统旨在确保您始终获取最新版本的付费墙，同时在网络条件有限的情况下也能保持可靠性。
loadTimeoutMs	默认值：5 秒	该值限制此方法的超时时间。若达到超时时间，将返回缓存数据或本地备用数据。 请注意，在极少数情况下，此方法的实际超时时间可能略晚于 loadTimeout 中指定的时间，因为该操作在底层可能由多个请求组成。 对于 Android：您可以使用扩展函数创建 TimeInterval（例如 5.seconds，其中 .seconds 来自 import com.adapty.utils.seconds），或使用 TimeInterval.seconds(5)。若不设置限制，请使用 TimeInterval.INFINITE。

响应参数：

参数	描述
Flow	一个 AdaptyFlow 对象，包含流程的标识符（id、variationId）、实验变体名称（variationName，可选，SDK 4.2+）、名称、版位、付费墙实验变体（paywalls）、任意远程配置（remoteConfigs），以及在 SDK 4.1 及更高版本中新增的 hasViewConfiguration 标志。

获取视图配置

如果版位是在 Flow & Paywall Builder 或旧版付费墙编辑工具中设计的，Adapty 会为您渲染 UI。使用 createFlowView 创建视图，然后展示流程或付费墙。如果该版位是没有编辑工具 UI 的自定义付费墙，请改为将其作为远程配置付费墙处理。

在 SDK 4.1 及更高版本中，流程上的 hasViewConfiguration 标志可在创建视图之前区分两者：

if (flow.hasViewConfiguration) {
  const view = await createFlowView(flow);
  await view.present();
} else {
  // Render your own screen from flow.remoteConfigs and flow.paywalls
}

在 4.0 版本中，该标志已被移除，对于没有视图配置的流程，createFlowView 会抛出 AdaptyError。

在 React Native SDK 中，直接调用 createFlowView 即可，无需提前获取视图配置。

try {
  const view = await createFlowView(flow);
} catch (error) {
  // handle the error
}

参数：

参数	是否必填	描述
flow	必填	用于获取目标流程/付费墙控制器的 AdaptyFlow 对象。
locale	可选	用于渲染视图的流程本地化标识符，例如 en 或 pt-br。若省略，视图将以 en 渲染，或在流程没有 en 时使用流程的默认本地化语言。需要 SDK 4.0.2 或更高版本。请参阅本地化与语言代码。
customLayoutId	可选 默认值：undefined SDK 4.1+	预留给尚未发布的 Flow & Paywall Builder 功能。在编辑工具支持定义布局 ID 之前，传入任何值都不会匹配到任何布局，createFlowView 将抛出 AdaptyError。请勿设置此参数。
customTags	可选	应用中对应流程自定义标签的值，以每个标签的完整名称为键的对象。详情请参阅向流程传递数据。
prefetchProducts	可选	启用后可优化屏幕上产品的展示时机。设为 true 时，AdaptyUI 将自动预加载所需产品。默认值：false。
android.enableSafeArea	可选	仅限 Android（在 iOS 上忽略）。请以嵌套对象形式传入：android: { enableSafeArea: true }。设为 true 时，流程视图将应用安全区域内边距。模态展示（createFlowView + present()）默认为 true，嵌入式 AdaptyFlowView 组件默认为 false。默认值适用于大多数场景。

获取视图后，请展示流程/付费墙。

为默认目标受众获取流程或付费墙以加快获取速度

通常，流程和付费墙的获取几乎是即时的，无需担心速度问题。但当你拥有大量目标受众和版位，且用户网络连接较弱时，获取流程或付费墙的时间可能会比预期更长。在这种情况下，你可能希望展示一个默认的流程或付费墙，以确保良好的用户体验，而不是让用户看到空白页面。

为了解决这个问题，你可以使用 getFlowForDefaultAudience 方法，该方法会获取指定版位中 All Users 目标受众的流程或付费墙。但请务必了解，推荐的做法是通过 getFlow 方法来获取流程或付费墙，详情请参阅上方的获取流程/付费墙章节。

try {
    const id = 'YOUR_PLACEMENT_ID';

    const flow = await adapty.getFlowForDefaultAudience(id);
  // the requested flow/paywall
} catch (error) {
    // handle the error
}

参数	是否必填	描述
placementId	必填	版位的标识符。该值是您在 Adapty 看板中创建版位时所指定的。
fetchPolicy	默认值：'reload_revalidating_cache_data'	fetchPolicy 决定 SDK 优先从哪一层读取数据，而非是否可以使用缓存。默认情况下，SDK 优先请求服务器，若请求失败则返回缓存数据。我们推荐此方式，因为它能确保用户始终获取最新数据。 但是，如果您认为用户的网络连接不稳定，可以考虑使用 'return_cache_data_else_load'，该策略的读取顺序相反——优先读取缓存，仅在没有缓存时才请求服务器。用户可能无法获取到最新数据，但无论网络状况如何，加载速度都会更快。缓存会定期更新，因此在会话期间使用缓存以减少网络请求是安全可靠的。 第三种策略 'return_cache_data_if_not_expired_else_load' 介于两者之间：在缓存时间早于您传入的 maxAgeSeconds 时优先读取缓存，超出时限后则请求服务器。 请注意，缓存在应用重启后依然保留，仅在应用重新安装或手动清理时才会被清除。

自定义资源

要自定义流程/付费墙中的图片和视频，请实现自定义资源。

主图和视频具有预定义的 ID：hero_image 和 hero_video。在自定义资源包中，你可以通过这些 ID 定位对应元素并自定义其行为。

对于其他图片和视频，你需要在 Adapty 看板中设置自定义 ID。

例如，你可以：

• 向部分用户展示不同的图片或视频。
• 在远程主图加载时显示本地预览图。
• 在视频播放前显示预览图。
• 展示随应用打包的媒体资源，让首屏无需下载即可渲染。请参阅从应用包中展示首屏媒体。

以下示例展示了如何通过简单字典提供自定义资源：

const customAssets: Record<string, AdaptyCustomAsset> = {
  'custom_image': { type: 'image', relativeAssetPath: 'custom_image.png' },
  'hero_video': {
    type: 'video',
    fileLocation: {
      ios: { fileName: 'custom_video.mp4' },
      android: { relativeAssetPath: 'videos/custom_video.mp4' }
    }
  }
};

view = await createFlowView(flow, { customAssets })

在 Adapty 看板中使用旧版付费墙编辑工具完成付费墙的视觉设计之后，你可以在移动应用中展示它。整个流程的第一步是获取与版位关联的付费墙及其视图配置，具体步骤如下。

在开始在移动应用中展示付费墙之前，请注意本主题适用于通过付费墙编辑工具自定义的付费墙。如果您是手动实现付费墙，请参阅在移动应用中为远程配置付费墙获取付费墙和产品主题。

在移动应用中开始展示付费墙之前（点击展开）

1. 在 Adapty 看板中创建产品。
2. 在 Adapty 看板中创建付费墙并将产品加入其中。
3. 在 Adapty 看板中创建版位并将付费墙加入其中。
4. 在移动应用中安装 Adapty SDK。

获取用付费墙编辑工具设计的付费墙

如果你已经使用付费墙编辑工具设计了付费墙，就无需在移动应用代码中手动编写渲染逻辑来向用户展示它。这类付费墙同时包含展示内容和展示方式。不过，你仍需通过版位获取其 ID 和视图配置，然后在移动应用中将其呈现出来。

为确保最佳性能，请尽早获取付费墙及其视图配置，以便在向用户展示之前有足够的时间下载图片。

使用 getPaywall 方法获取付费墙：

try {
    const placementId = 'YOUR_PLACEMENT_ID';
    const locale = 'en';

    const paywall = await adapty.getPaywall(placementId, locale);
  // the requested paywall
} catch (error) {
    // handle the error
}

参数：

参数	是否必填	说明
placementId	必填	目标版位的标识符。即你在 Adapty 看板中创建版位时指定的值。
locale	可选 默认值：en	付费墙本地化的标识符。该参数应为语言代码，由一个或两个子标签组成，以连字符（-）分隔。第一个子标签表示语言，第二个子标签表示地区。 示例：en 表示英语，pt-br 表示巴西葡萄牙语。 有关语言区域代码及使用建议，请参阅本地化与语言区域代码。
fetchPolicy	默认值：'reload_revalidating_cache_data'	fetchPolicy 决定 SDK 优先从哪一层读取数据，而非是否可以使用缓存。默认情况下，SDK 会优先请求服务器，若请求失败则返回缓存数据。我们推荐这种方式，因为它能确保用户始终获取最新数据。 但如果你认为用户的网络环境不稳定，可以考虑使用 'return_cache_data_else_load'，该策略会反转优先级——优先读取缓存，仅在无缓存时才请求服务器。用户获取的数据可能不是最新的，但无论网络状况如何，加载速度都会更快。缓存会定期更新，因此在会话期间使用缓存以减少网络请求是安全的。 第三种策略 'return_cache_data_if_not_expired_else_load' 介于两者之间：当缓存数据的存活时间小于你传入的 maxAgeSeconds 时，优先读取缓存；超过该时限后则请求服务器。 请注意，缓存在应用重启后仍然保留，仅在应用重新安装或手动清除时才会被清空。 Adapty SDK 在两个层级中本地存储付费墙：上述定期更新的缓存层，以及备用付费墙。我们还使用 CDN 加速付费墙的加载，并在 CDN 不可用时提供独立的备用服务器。该机制旨在确保你始终获取最新版本的付费墙，同时在网络条件较差的情况下也能保证可用性。
loadTimeoutMs	默认值：5 秒	该值限制此方法的超时时间。若超时，将返回缓存数据或本地备用数据。 请注意，在极少数情况下，此方法的实际超时时间可能略晚于 loadTimeout 中指定的值，因为该操作在底层可能包含多个请求。 对于 Android：你可以使用扩展函数创建 TimeInterval（例如 5.seconds，其中 .seconds 来自 import com.adapty.utils.seconds），或使用 TimeInterval.seconds(5)。如需不设限制，请使用 TimeInterval.INFINITE。

响应参数：

参数	描述
Paywall	一个 AdaptyPaywall 对象，包含产品 ID 列表、付费墙标识符、远程配置及其他若干属性。

获取使用付费墙编辑工具设计的付费墙的视图配置

获取付费墙后，检查它是否包含 ViewConfiguration，这表明它是使用付费墙编辑工具创建的。这将指导您如何展示该付费墙。如果存在 ViewConfiguration，将其作为付费墙编辑工具付费墙处理；否则，将其作为远程配置付费墙处理。

在 React Native SDK 中，直接调用 createPaywallView 方法，无需手动预先获取视图配置。

// for the Adapty SDK < 3.14 – import {createPaywallView} from 'react-native-adapty/dist/ui';

if (paywall.hasViewConfiguration) {
  try {
    const view = await createPaywallView(paywall);
  } catch (error) {
    // handle the error
  }
} else {
    //use your custom logic
}

参数：

参数	是否必填	说明
paywall	必填	AdaptyPaywall 对象，用于获取目标付费墙的控制器。
customTags	可选	定义自定义标签及其对应值的字典。自定义标签作为付费墙内容中的占位符，在运行时动态替换为特定字符串，实现付费墙内容的个性化展示。详情请参阅付费墙编辑工具中的自定义标签相关主题。
prefetchProducts	可选	启用后可优化产品在屏幕上的显示时机。设为 true 时，AdaptyUI 将自动预取所需产品。默认值：false。

获取视图后，展示付费墙。

为默认目标受众获取付费墙以加快获取速度

通常情况下，付费墙几乎可以立即获取，因此您无需担心加快此过程。但是，当您拥有大量目标受众和付费墙，且用户网络连接较弱时，获取付费墙可能需要比预期更长的时间。在这种情况下，您可能希望展示默认付费墙，以确保流畅的用户体验，而非不展示任何付费墙。

为解决这一问题，您可以使用 getPaywallForDefaultAudience 方法，该方法获取指定版位针对所有用户目标受众的付费墙。但请务必了解，推荐的方式是通过 getPaywall 方法获取付费墙，详见上方获取付费墙信息部分。

try {
    const id = 'YOUR_PLACEMENT_ID';
    const locale = 'en';

    const paywall = await adapty.getPaywallForDefaultAudience(id, locale);
  // the requested paywall
} catch (error) {
    // handle the error
}

参数	是否必填	描述
placementId	必填	版位的标识符。这是您在 Adapty 看板中创建版位时所指定的值。
locale	可选 默认值：en	付费墙本地化的标识符。该参数应为由一个或多个子标签组成的语言代码，子标签之间用连字符（-）分隔。第一个子标签表示语言，第二个子标签表示地区。 示例：en 表示英语，pt-br 表示巴西葡萄牙语。 有关语言区域代码及推荐用法的详细信息，请参阅本地化与语言区域代码。
fetchPolicy	默认值：'reload_revalidating_cache_data'	fetchPolicy 用于设置 SDK 优先读取哪一层数据，而非是否可以使用缓存。默认情况下，SDK 会优先请求服务器，若请求失败则返回缓存数据。我们推荐使用此策略，因为它能确保用户始终获取最新数据。 但如果您认为用户的网络环境不稳定，可以考虑使用 'return_cache_data_else_load'，该策略采用相反的顺序——优先读取缓存，仅当缓存为空时才请求服务器。用户获取的数据可能不是最新的，但无论网络状况如何，加载速度都会更快。缓存会定期更新，因此在会话期间使用缓存以减少网络请求是安全的。 第三种策略 'return_cache_data_if_not_expired_else_load' 介于两者之间：当缓存数据的存储时间短于您传入的 maxAgeSeconds 时，优先读取缓存；超过该时间后则请求服务器。 请注意，缓存在应用重启后仍然保留，仅在卸载应用或手动清理时才会被清除。

自定义素材资源

要自定义付费墙中的图片和视频，请实现自定义素材资源。

主图和视频具有预定义的 ID：hero_image 和 hero_video。在自定义素材资源包中，您通过这些 ID 定位对应元素并自定义其行为。

对于其他图片和视频，您需要在 Adapty 看板中设置自定义 ID。

例如，您可以：

• 向部分用户展示不同的图片或视频。
• 在远程主图加载期间展示本地预览图。
• 在播放视频前展示预览图。

以下是通过简单字典提供自定义素材资源的示例：

const customAssets: Record<string, AdaptyCustomAsset> = {
  'custom_image': { type: 'image', relativeAssetPath: 'custom_image.png' },
  'hero_video': {
    type: 'video',
    fileLocation: {
      ios: { fileName: 'custom_video.mp4' },
      android: { relativeAssetPath: 'videos/custom_video.mp4' }
    }
  }
};

view = await createPaywallView(paywall, { customAssets })