在 Flutter SDK 中展示用户引导

如果您已使用编辑工具自定义了用户引导，则无需在 Flutter 应用代码中手动处理渲染逻辑来向用户展示它。这类用户引导已同时包含展示内容和展示方式。

在开始之前，请确认：

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

Adapty Flutter SDK 提供两种展示用户引导的方式：

• 独立页面

• 嵌入式组件

以独立屏幕展示

要将用户引导以独立屏幕的方式展示，请对由 createOnboardingView 方法创建的 onboardingView 调用 onboardingView.present() 方法。每个 view 只能使用一次。如果需要再次展示用户引导，请重新调用 createOnboardingView 创建新的 onboardingView 实例。

try {
  await onboardingView.present();
} on AdaptyError catch (e) {
  // handle the error
} catch (e) {
  // handle the error
}

关闭用户引导

当需要以编程方式关闭用户引导时，请使用 dismiss() 方法：

try {
  await onboardingView.dismiss();
} on AdaptyError catch (e) {
  // handle the error
} catch (e) {
  // handle the error
}

配置 iOS 展示样式

通过向 present() 方法传入 iosPresentationStyle 参数，可配置用户引导在 iOS 上的展示方式。该参数接受 AdaptyUIIOSPresentationStyle.fullScreen（默认值）或 AdaptyUIIOSPresentationStyle.pageSheet 值。

try {
  await onboardingView.present(iosPresentationStyle: AdaptyUIIOSPresentationStyle.pageSheet);
} on AdaptyError catch (e) {
  // handle the error
} catch (e) {
  // handle the error
}

嵌入组件层级

如需将用户引导嵌入现有的组件树，可直接在 Flutter 组件层级中使用 AdaptyUIOnboardingPlatformView 组件。

AdaptyUIOnboardingPlatformView(
  onboarding: onboarding, // The onboarding object you fetched
  onDidFinishLoading: (meta) {
  },
  onDidFailWithError: (error) {
  },
  onCloseAction: (meta, actionId) {
  },
  onPaywallAction: (meta, actionId) {
  },
  onCustomAction: (meta, actionId) {
  },
  onStateUpdatedAction: (meta, elementId, params) {
  },
  onAnalyticsEvent: (meta, event) {
  },
)

class MainActivity : FlutterFragmentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
    }
}

用户引导加载中

展示用户引导时，你可能会注意到在启动页与用户引导之间有一个短暂的加载界面，这是底层视图初始化时出现的。你可以根据实际需求采用不同的方式来处理这种情况。

通过 onDidFinishLoading 控制启动页

推荐的跨平台方案是：保持启动页或自定义遮罩层可见，直到用户引导完全加载完成，再手动将其隐藏。

使用嵌入式 widget 时，在其上方叠加自定义 widget，并在 onDidFinishLoading 触发时隐藏遮罩层：

AdaptyUIOnboardingPlatformView(
  onboarding: onboarding,
  onDidFinishLoading: (meta) {
    // Hide your custom splash screen or overlay here
  },
  // ... other callbacks
)

自定义原生加载界面

如果需要自定义默认加载界面本身，可以使用平台专属布局进行替换。此方式需要分别针对 Android 和 iOS 进行实现：

• iOS：将 AdaptyOnboardingPlaceholderView.xib 添加到您的 Xcode 项目中
• Android：在 res/layout 中创建 adapty_onboarding_placeholder_view.xml 并在其中定义占位视图

自定义用户引导中链接的打开方式

默认情况下，用户引导中的链接会在应用内浏览器中打开。这样可以在应用内直接展示网页，用户无需切换应用，体验更流畅。

如果你希望改为在外部浏览器中打开链接，可以将 externalUrlsPresentation 参数设置为 AdaptyWebPresentation.externalBrowser 来自定义此行为：

final onboardingView = await AdaptyUI().createOnboardingView(
  onboarding: onboarding,
  externalUrlsPresentation: AdaptyWebPresentation.externalBrowser, // default – AdaptyWebPresentation.inAppBrowser
);

try {
  await onboardingView.present();
} on AdaptyError catch (e) {
  // handle the error
} catch (e) {
  // handle the error
}

AdaptyUIOnboardingPlatformView(
  onboarding: onboarding,
  externalUrlsPresentation: AdaptyWebPresentation.externalBrowser, // default – AdaptyWebPresentation.inAppBrowser
  onDidFinishLoading: (meta) {
  },
  onDidFailWithError: (error) {
  },
  onCloseAction: (meta, actionId) {
  },
  onPaywallAction: (meta, actionId) {
  },
  onCustomAction: (meta, actionId) {
  },
  onStateUpdatedAction: (meta, elementId, params) {
  },
  onAnalyticsEvent: (meta, event) {
  },
)

禁用安全区域内边距（Android）

默认情况下，在 Android 设备上，用户引导视图会自动应用安全区域内边距，以避开状态栏和导航栏等系统 UI 元素。如果你希望禁用此行为并完全自定义布局，可以在应用中添加一个布尔类型资源：

1. 进入 android/app/src/main/res/values 目录。如果不存在 bools.xml 文件，请新建一个。

2. 添加以下资源：

<resources>
    <bool name="adapty_onboarding_enable_safe_area_paddings">false</bool>
</resources>

请注意，这些更改将对您应用中的所有用户引导全局生效。