获取流程与付费墙 - Flutter

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

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

在开始于您的移动应用中展示流程和付费墙之前（点击展开）

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

获取流程/付费墙

如果你已使用流程编辑工具或付费墙编辑工具设计了流程或付费墙，则无需在移动应用代码中手动处理其渲染逻辑来向用户展示。此类流程或付费墙已包含展示内容和展示方式的完整配置。不过，你仍需通过版位获取其 ID 和视图配置，然后在移动应用中进行呈现。 尽早获取流程或付费墙并创建其视图——最好在展示之前就提前完成。createFlowView 方法会加载视图配置，并在后台开始下载和缓存图片。调用时机越早，下载完成的时间就越充裕。等到真正展示流程或付费墙时，其配置和图片往往已经缓存好、随时可用。

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

try {
  final flow = await Adapty().getFlow(placementId: 'YOUR_PLACEMENT_ID');
  // the requested flow/paywall
} on AdaptyError catch (adaptyError) {
  // handle the error
} catch (e) {
  // handle the error
}

参数：

参数	是否必填	描述
placementId	必填	目标版位的标识符。这是你在 Adapty 看板中创建版位时指定的值。
fetchPolicy	默认：.reloadRevalidatingCacheData	默认情况下，SDK 会尝试从服务器加载数据，若加载失败则返回缓存数据。我们推荐使用此选项，因为它能确保用户始终获取最新数据。 但如果你认为用户的网络连接不稳定，可以考虑使用 .returnCacheDataElseLoad——在缓存存在的情况下直接返回缓存数据。这样用户获取的数据可能不是最新的，但无论网络状况多差，加载速度都会更快。缓存会定期更新，因此在会话期间使用缓存来减少网络请求是安全可靠的。 请注意，缓存在应用重启后依然保留，只有在应用重新安装或手动清除时才会被清空。 Adapty SDK 通过两层机制在本地存储付费墙：上述定期更新的缓存，以及备用付费墙。我们还使用 CDN 来加快付费墙的获取速度，并在 CDN 不可用时提供独立的备用服务器。整套机制旨在确保你始终能获取最新版本的付费墙，同时在网络条件较差时也能保证可靠性。
loadTimeout	默认：5 秒	限制该方法超时时间的 Duration 值。若超时，将返回缓存数据或本地备用数据。 请注意，在极少数情况下，该方法的实际超时时间可能略晚于 loadTimeout 中指定的时间，因为底层操作可能由多个请求组成。
响应参数：
参数	描述
:--------	:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Flow	一个 AdaptyFlow 对象，包含流程的标识符（instanceIdentity、variationId）、名称、版位、其付费墙实验变体（paywalls）以及任何远程配置（remoteConfigs）。

获取视图配置

如果版位是在 Flow Builder 或 Paywall Builder 中设计的，Adapty 会自动为你渲染 UI —— 所获取的 flow 的 hasViewConfiguration 属性为 true。使用 createFlowView 创建视图，然后展示 flow 或付费墙。如果版位是未使用编辑工具的自定义付费墙（hasViewConfiguration 为 false），请改为将其作为远程配置付费墙处理。

try {
  final view = await AdaptyUI().createFlowView(flow: flow);
} on AdaptyError catch (e) {
  // handle the error
} catch (e) {
  // handle the error
}

参数：

参数	是否必填	描述
flow	必填	一个 AdaptyFlow 对象，用于获取所需流程/付费墙的视图。
customTags	选填	定义自定义标签及其对应值的映射。自定义标签作为内容中的占位符，在流程/付费墙中动态替换为指定字符串，实现个性化内容。详情请参阅付费墙编辑工具中的自定义标签。
preloadProducts	选填	启用后可优化产品在屏幕上的显示时机。设为 true 时，AdaptyUI 将自动预加载所需产品。默认值：false。
loadTimeout	选填	一个 Duration，用于限制视图配置的加载超时时间。若超时，将使用缓存数据或本地备用内容。

完成视图设置后，展示流程/付费墙。

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

通常情况下，流程和付费墙的加载几乎是即时完成的，无需担心速度问题。但如果你配置了大量目标受众和版位，且用户的网络连接较弱，加载流程或付费墙可能会比预期慢。在这种情况下，你可能希望先展示默认流程或付费墙，以保证用户体验的流畅性，而不是什么都不显示。 为了解决这个问题，你可以使用 getFlowForDefaultAudience 方法，该方法会获取指定版位中针对 All Users 目标受众的流程或付费墙。但需要特别注意的是，推荐的做法是通过 getFlow 方法来获取流程或付费墙，详情请参阅上方的获取流程/付费墙章节。

try {
  final flow = await Adapty().getFlowForDefaultAudience(placementId: 'YOUR_PLACEMENT_ID');
  // the requested flow/paywall
} on AdaptyError catch (adaptyError) {
  // handle error
} catch (e) {
  // handle unknown error
}

参数	是否必填	描述
placementId	必填	版位 的标识符。这是您在 Adapty 看板中创建版位时所指定的值。
fetchPolicy	默认值：.reloadRevalidatingCacheData	默认情况下，SDK 会尝试从服务器加载数据，若加载失败则返回缓存数据。我们推荐使用此方案，因为它能确保用户始终获取最新数据。 但如果您认为用户的网络环境不稳定，可以考虑使用 .returnCacheDataElseLoad——当缓存数据存在时直接返回缓存。这样一来，用户获取的数据可能不是最新的，但无论网络状况如何，加载速度都会更快。缓存会定期更新，因此在会话期间使用缓存来减少网络请求是安全的。 请注意，重启应用后缓存依然保留，只有在重新安装应用或手动清理时才会被清除。

自定义资源

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

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

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

例如，您可以：

• 向部分用户展示不同的图片或视频。
• 在远程主图加载时，先显示本地预览图。
• 在播放视频前先显示预览图。 以下是如何通过简单字典提供自定义资源的示例：

final customAssets = {
    // Show a local image using a custom ID
    'custom_image': AdaptyCustomAsset.localImageAsset(
        assetId: 'assets/images/image_name.png',
    ),

    // Show a local video with a preview image
    'hero_video': AdaptyCustomAsset.localVideoAsset(
        assetId: 'assets/videos/custom_video.mp4',
    ),
};

try {
  final view = await AdaptyUI().createFlowView(
    flow: flow,
    customAssets: customAssets,
  );
} on AdaptyError catch (e) {
  // handle the error
} catch (e) {
  // handle the error
}

设置开发者自定义计时器

要在移动应用中使用自定义计时器，请将 customTimers 映射传递给 createFlowView 方法。映射中每个键为计时器 ID，对应的值为定义计时器结束时间的 DateTime 对象。示例如下：

try {
  final view = await AdaptyUI().createFlowView(
    flow: flow,
    customTimers: {
      'CUSTOM_TIMER_6H': DateTime.now().add(const Duration(seconds: 3600 * 6)),
      'CUSTOM_TIMER_NY': DateTime(2027, 1, 1), // New Year 2027
    },
  );
} on AdaptyError catch (e) {
  // handle the error
} catch (e) {
  // handle the error
}

在此示例中，CUSTOM_TIMER_NY 和 CUSTOM_TIMER_6H 是你在 Adapty 看板中设置的开发者自定义计时器的 Timer ID。customTimers 映射可确保你的应用动态地为每个计时器更新正确的值。例如：

• CUSTOM_TIMER_NY：距计时器结束时间（如元旦）的剩余时间。
• CUSTOM_TIMER_6H：用户打开流程后，6 小时倒计时的剩余时间。

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

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

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

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

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

如果你已经使用付费墙编辑工具设计了付费墙，就无需在移动应用代码中手动处理渲染逻辑来向用户展示它。这类付费墙同时包含展示内容和展示方式。不过，你仍需通过版位获取其 ID 和视图配置，然后在移动应用中将其呈现出来。 为确保最佳性能，请尽早获取付费墙及其视图配置，以便在向用户展示之前有足够的时间完成图片下载。

使用 getPaywall 方法获取付费墙：

try {
  final paywall = await Adapty().getPaywall(placementId: "YOUR_PLACEMENT_ID", locale: "en");
  // the requested paywall
} on AdaptyError catch (adaptyError) {
  // handle the error
} catch (e) {
}

参数：

参数	是否必填	描述
placementId	必填	目标版位的标识符。这是你在 Adapty 看板中创建版位时指定的值。
locale	可选 默认值：en	付费墙本地化的标识符。该参数应为语言代码，由一个或两个子标签组成，子标签之间用连字符（-）分隔。第一个子标签表示语言，第二个子标签表示地区。 示例：en 表示英语，pt-br 表示巴西葡萄牙语。 有关语言区域代码及推荐用法，请参阅本地化与语言区域代码。
fetchPolicy	默认值：.reloadRevalidatingCacheData	默认情况下，SDK 会尝试从服务器加载数据，若加载失败则返回缓存数据。我们推荐使用此方式，因为它能确保用户始终获取最新数据。 但如果你认为用户的网络环境不稳定，可以考虑使用 .returnCacheDataElseLoad，在缓存存在时直接返回缓存数据。这种情况下，用户获取的数据可能不是最新的，但无论网络状况如何，加载速度都会更快。缓存会定期更新，因此在会话期间使用缓存以减少网络请求是安全的。 请注意，缓存在应用重启后仍然保留，只有在重新安装应用或手动清除时才会被清空。 Adapty SDK 在本地以两层方式存储付费墙：上述定期更新的缓存，以及备用付费墙。我们还使用 CDN 加快付费墙的获取速度，并在 CDN 不可用时提供独立的备用服务器。这套机制旨在确保你始终获取最新版本的付费墙，同时在网络条件较差的情况下也能保证可靠性。
loadTimeout	默认值：5 秒	该值限制此方法的超时时间。若超时，将返回缓存数据或本地备用数据。 请注意，在极少数情况下，此方法的实际超时时间可能略晚于 loadTimeout 中指定的时间，因为底层操作可能包含多个请求。 对于 Android：你可以使用扩展函数创建 TimeInterval（例如 5.seconds，其中 .seconds 来自 import com.adapty.utils.seconds），或使用 TimeInterval.seconds(5)。如需不设限制，请使用 TimeInterval.INFINITE。
响应参数：
参数	描述
:--------	:----------------------------------------------------------------------------------------------------------------------------------------------------------
Paywall	一个 AdaptyPaywall 对象，包含产品 ID 列表、付费墙标识符、远程配置及其他若干属性。

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

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

try {
  final view = await AdaptyUI().createPaywallView(
        paywall: paywall,
      );
} on AdaptyError catch (e) {
  // handle the error
} catch (e) {
  // handle the error
}

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

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

通常情况下，付费墙的获取几乎是即时完成的，无需担心速度问题。但如果你配置了大量目标受众和付费墙，且用户的网络连接较差，获取付费墙可能会比预期耗时更长。在这种情况下，你可能希望优先展示默认付费墙，以保证流畅的用户体验，而不是让用户看到空白页面。 要解决这个问题，你可以使用 getPaywallForDefaultAudience 方法，它会获取指定版位中 All Users 目标受众对应的付费墙。但需要特别注意的是，推荐的做法是通过 getPaywall 方法来获取付费墙，详见上方的获取付费墙信息章节。

try {
    final paywall = await Adapty().getPaywallForDefaultAudience(placementId: 'YOUR_PLACEMENT_ID');
} on AdaptyError catch (adaptyError) {
    // handle error
} catch (e) {
    // handle unknown error
}

参数	是否必填	描述
placementId	必填	版位的标识符。这是你在 Adapty 看板中创建版位时指定的值。
locale	可选 默认值：en	付费墙本地化的标识符。该参数应为语言代码，由一个或多个子标签组成，子标签之间用短横线（-）分隔。第一个子标签表示语言，第二个子标签表示地区。 示例：en 表示英语，pt-br 表示巴西葡萄牙语。 有关语言区域代码及推荐使用方式，请参阅本地化与语言区域代码。
fetchPolicy	默认值：.reloadRevalidatingCacheData	默认情况下，SDK 会尝试从服务器加载数据，若失败则返回缓存数据。我们推荐使用此方式，因为它能确保用户始终获取最新数据。 不过，如果你认为用户的网络状况不稳定，可以考虑使用 .returnCacheDataElseLoad——在缓存数据存在时直接返回缓存。这种方式下用户获取的数据可能不是最新的，但无论网络状况如何，加载速度都会更快。缓存会定期更新，因此在会话期间使用缓存来避免网络请求是安全的。 请注意，缓存在应用重启后依然保留，只有在应用重新安装或手动清除时才会被清空。

自定义资源

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

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

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

例如，你可以：

• 为部分用户显示不同的图片或视频。
• 在远程主图加载时，先显示本地预览图。
• 在播放视频前显示预览图片。

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

final customAssets = {
    // Show a local image using a custom ID
    'custom_image': AdaptyCustomAsset.localImageAsset(
        assetId: 'assets/images/image_name.png',
    ),

    // Show a local video with a preview image
    'hero_video': AdaptyCustomAsset.localVideoAsset(
        assetId: 'assets/videos/custom_video.mp4',
    ),
};

try {
  final view = await AdaptyUI().createPaywallView(
    paywall: paywall,
    customAssets: customAssets,
  );
} on AdaptyError catch (e) {
  // handle the error
} catch (e) {
  // handle the error
}

设置自定义计时器

要在移动应用中使用自定义计时器，请将 customTimers 映射传递给 createPaywallView 方法。映射中的每个键是计时器 ID，对应的值是一个 DateTime 对象，用于定义计时器的结束时间。示例如下：

try {
  final view = await AdaptyUI().createPaywallView(
        paywall: paywall,
        customTimers: {
          'CUSTOM_TIMER_6H': DateTime.now().add(const Duration(seconds: 3600 * 6)),
          'CUSTOM_TIMER_NY': DateTime(2025, 1, 1), // New Year 2025
        },
      );
} on AdaptyError catch (e) {
  // handle the error
} catch (e) {
  // handle the error
}

在此示例中，CUSTOM_TIMER_NY 和 CUSTOM_TIMER_6H 是您在 Adapty 看板中设置的开发者自定义计时器的 Timer ID。customTimers 映射确保您的应用为每个计时器动态更新正确的值。例如：

• CUSTOM_TIMER_NY：距计时器结束时间（如元旦）的剩余时长。
• CUSTOM_TIMER_6H：从用户打开付费墙开始计算的 6 小时倒计时剩余时长。