在 Kotlin Multiplatform SDK 中展示用户引导

用户引导功能已在 SDK v4 中弃用，并将在未来版本中移除。 该功能不再接受修复或改进。请改用流程：与在 WebView 中运行的用户引导不同，流程直接在设备上原生渲染——动画更流畅、外观与原生体验一致、加载速度更快，且无需依赖 WebView 运行时。请参阅获取流程与付费墙和展示流程与付费墙以开始使用。

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

在开始之前，请确保：

您已安装 Adapty Kotlin Multiplatform SDK 3.16.1 或更高版本。
您已创建用户引导。
您已将用户引导添加到版位。

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

使用 Compose Multiplatform
不使用 Compose Multiplatform

使用 Compose Multiplatform

要显示用户引导，请在通过 createOnboardingView 方法创建的 view 上调用 view.present() 方法。每个 view 只能使用一次。如果需要再次显示用户引导，请再次调用 createOnboardingView 创建一个新的 view 实例。

在未重新创建的情况下复用同一个 view 可能会导致错误。


viewModelScope.launch {
    AdaptyUI.createOnboardingView(onboarding = onboarding).onSuccess { view ->
        view.present()
    }.onError { error ->
        // handle the error
    }
}

配置 iOS 呈现样式

通过向 present() 方法传递 iosPresentationStyle 参数，可以配置用户引导在 iOS 上的呈现方式。该参数接受 AdaptyUIIOSPresentationStyle.FULLSCREEN（默认值）或 AdaptyUIIOSPresentationStyle.PAGESHEET。


viewModelScope.launch {
    val view = AdaptyUI.createOnboardingView(onboarding = onboarding).getOrNull()
    view?.present(iosPresentationStyle = AdaptyUIIOSPresentationStyle.PAGESHEET)
}

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

默认情况下，用户引导中的链接会在应用内浏览器中打开。这种方式能让用户无需切换应用即可浏览网页，提供流畅的使用体验。

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


viewModelScope.launch {
    AdaptyUI.createOnboardingView(
        onboarding = onboarding,
        externalUrlsPresentation = AdaptyWebPresentation.EXTERNAL_BROWSER // default – IN_APP_BROWSER
    ).onSuccess { view ->
        view.present()
    }.onError { error ->
        // handle the error
    }
}

不使用 Compose Multiplatform

createNativeOnboardingView 是核心模块 io.adapty:adapty-kmp 的一部分。如果你的项目不使用 Compose Multiplatform，则无需添加 io.adapty:adapty-kmp-ui 依赖。

如需在不使用 Compose Multiplatform 的情况下嵌入用户引导，请调用 createNativeOnboardingView。它会返回一个 AdaptyNativeOnboardingView，你可以将其添加到布局中：


val nativeView = AdaptyUI.createNativeOnboardingView(
    context = context,
    viewModelStoreOwner = activity,
    onboarding = onboarding,
    observer = myOnboardingObserver,
)

// Embed in your Compose layout:
AndroidView(
    factory = { nativeView.view },
    modifier = Modifier.fillMaxSize()
)

由于 KMP 接口的默认方法在 Swift 中会变成 @required，你无法在 Swift 中直接实现 AdaptyUIOnboardingsEventsObserver。请先在 iosMain 中声明一个 open 基类：

open class BaseOnboardingObserver : AdaptyUIOnboardingsEventsObserver

然后在 Swift 中继承它，只覆盖你需要的方法：

class MyOnboardingObserver: BaseOnboardingObserver {
    override func onboardingViewOnCloseAction(
        view: AdaptyUIOnboardingView,
        meta: AdaptyUIOnboardingMeta,
        actionId: String
    ) {
        // remove nativeView from your view hierarchy
    }
}

let nativeView = AdaptyUI.shared.createNativeOnboardingView(
    onboarding: onboarding,
    observer: MyOnboardingObserver()
)
// nativeView.viewController is a UIViewController.
// Add it to your SwiftUI view or UIKit hierarchy.

释放视图

从布局中移除视图时，请调用 dispose()。此操作将注销事件监听器并释放内部资源。

nativeView.dispose()