在 Flutter SDK 中获取用户引导

在 Adapty 看板中使用编辑工具设计好用户引导的视觉部分后，您可以在 Flutter 应用中展示它。此过程的第一步是获取与版位关联的用户引导及其视图配置，具体如下所述。

开始之前，请确保：

已安装 Adapty Flutter SDK 3.8.0 或更高版本。
已创建用户引导。
已将用户引导添加到版位。

获取用户引导

当您使用我们的无代码编辑工具创建用户引导时，它会以容器形式存储，包含您的应用需要获取并展示的配置信息。该容器管理整个体验——显示哪些内容、如何呈现，以及如何处理用户交互（如测验答案或表单输入）。容器还会自动追踪分析事件，因此您无需单独实现视图追踪。

为获得最佳性能，请尽早获取用户引导配置，以便在向用户展示之前有足够时间下载图片。

要获取用户引导，请使用 getOnboarding 方法：

try {
  final onboarding = await Adapty().getOnboarding(placementId: "YOUR_PLACEMENT_ID");
} on AdaptyError catch (e) {
    //handle error
} catch (e) { 
    //handle error
}

然后，调用 createOnboardingView 方法获取将要展示的视图。

createOnboardingView 方法的结果只能使用一次。如果需要再次使用，请重新调用 createOnboardingView 方法。在不重新创建的情况下调用两次可能会导致 AdaptyUIError.viewAlreadyPresented 错误。

import 'package:adapty_flutter/adapty_flutter.dart';

try {
    final onboardingView = await Adapty().createOnboardingView(onboarding: onboarding);
} on AdaptyError catch (e) { 
    //handle error
} catch (e) { 
    //handle error
}

参数：

参数	是否必填	描述
placementId	必填	所需版位的标识符。这是您在 Adapty 看板中创建版位时指定的值。
locale	可选默认值：`en`	用户引导本地化的标识符。该参数应为由一个或两个子标签组成的语言代码，子标签之间用减号（-）分隔。第一个子标签表示语言，第二个表示地区。示例：`en` 表示英语，`pt-br` 表示巴西葡萄牙语。
fetchPolicy	默认值：`.reloadRevalidatingCacheData`	默认情况下，SDK 会尝试从服务器加载数据，若失败则返回缓存数据。我们推荐此选项，因为它能确保用户始终获得最新数据。但是，如果您认为用户的网络连接不稳定，可以考虑使用 `.returnCacheDataElseLoad`，在缓存数据存在时直接返回缓存。在这种情况下，用户可能无法获得最新数据，但无论网络状况如何，都能体验更快的加载速度。缓存会定期更新，因此在会话期间使用缓存以避免网络请求是安全的。请注意，缓存在重启应用后依然保留，仅在重新安装应用或手动清理时才会清除。 Adapty SDK 在本地以两层方式存储用户引导：上述定期更新的缓存层和备用用户引导层。我们还使用 CDN 加速用户引导的获取，并在 CDN 不可访问时使用独立备用服务器。该系统旨在确保您始终获得最新版本的用户引导，同时在网络连接稀缺的情况下也能保证可靠性。
loadTimeout	默认值：5 秒	该值限制此方法的超时时间。如果达到超时，将返回缓存数据或本地备用数据。请注意，在极少数情况下，此方法的实际超时可能略晚于 `loadTimeout` 中指定的时间，因为该操作在底层可能由多个不同请求组成。

响应参数：

参数	描述
Onboarding	一个 `AdaptyOnboarding` 对象，包含：用户引导标识符和配置、远程配置以及其他几个属性。

使用默认目标受众用户引导加速获取

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

为解决这一问题，您可以使用 getOnboardingForDefaultAudience 方法，该方法会获取指定版位中针对所有用户目标受众的用户引导。但请务必了解，推荐的方式仍是通过 getOnboarding 方法获取用户引导，详见上方的获取用户引导部分。

请考虑使用 getOnboarding 而非 getOnboardingForDefaultAudience，因为后者有以下重要限制：

兼容性问题：在支持多个应用版本时可能产生问题，需要设计向后兼容的界面，否则旧版本可能显示异常。
无个性化：仅显示”所有用户”目标受众的内容，无法基于国家、归因或自定义属性进行定向。

如果在您的使用场景中更快的获取速度优于上述缺点，请按以下方式使用 getOnboardingForDefaultAudience。否则，请按上方所述使用 getOnboarding。

try {
    final onboarding = await Adapty().getOnboardingForDefaultAudience(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，在缓存数据存在时直接返回缓存。在这种情况下，用户可能无法获得最新数据，但无论网络状况如何，都能体验更快的加载速度。缓存会定期更新，因此在会话期间使用缓存以避免网络请求是安全的。

请注意，缓存在重启应用后依然保留，仅在重新安装应用或手动清理时才会清除。

Adapty SDK 在本地以两层方式存储用户引导：上述定期更新的缓存层和备用用户引导层。我们还使用 CDN 加速用户引导的获取，并在 CDN 不可访问时使用独立备用服务器。该系统旨在确保您始终获得最新版本的用户引导，同时在网络连接稀缺的情况下也能保证可靠性。