在 Kotlin Multiplatform SDK 中处理用户引导事件

在开始之前，请确保：

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

使用编辑工具配置的用户引导会生成您的应用可以响应的事件。请参阅以下内容了解如何响应这些事件。

设置用户引导事件观察者

要处理用户引导事件，您需要实现 AdaptyUIOnboardingsEventsObserver 接口，并通过 AdaptyUI.setOnboardingsEventsObserver() 进行设置。这应在应用生命周期的早期完成，通常在主 Activity 或应用初始化时进行。

import com.adapty.kmp.AdaptyUI

import com.adapty.kmp.AdaptyUIOnboardingsEventsObserver

// In your app initialization
AdaptyUI.setOnboardingsEventsObserver(MyAdaptyUIOnboardingsEventsObserver())

自定义操作

在编辑工具中，你可以为按钮添加 custom 操作并为其分配一个 ID。然后，你可以在代码中使用该 ID，并将其作为自定义操作进行处理。

例如，当用户点击自定义按钮（如 Login 或 Allow notifications）时，委托方法 onCustomAction 将被触发，并携带来自编辑工具的操作 ID。您可以创建自己的 ID，例如 “allowNotifications”。

import com.adapty.kmp.Adapty

import com.adapty.kmp.AdaptyUI
import com.adapty.kmp.AdaptyUIOnboardingsEventsObserver

import com.adapty.kmp.models.AdaptyUIOnboardingView
import com.adapty.kmp.models.AdaptyUIOnboardingMeta

class MyAdaptyUIOnboardingsEventsObserver : AdaptyUIOnboardingsEventsObserver {
    override fun onboardingViewOnCustomAction(
        view: AdaptyUIOnboardingView,
        meta: AdaptyUIOnboardingMeta,
        actionId: String
    ) {
        when (actionId) {
            "openPaywall" -> {
                // Display paywall from onboarding
                // You would typically fetch and present a new paywall here
                mainUiScope.launch {
                    // Example: Get paywall by placement ID
                    // val paywallResult = Adapty.getPaywall("your_placement_id")
                    // paywallResult.onSuccess { paywall ->
                    //     val paywallViewResult = AdaptyUI.createPaywallView(paywall)
                    //     paywallViewResult.onSuccess { paywallView ->
                    //         paywallView.present()
                    //     }
                    // }
                }
            }
            "allowNotifications" -> {
                // Handle notification permissions
            }
            else -> {
                // Handle other custom actions
            }
        }
    }
}

// Set up the observer
AdaptyUI.setOnboardingsEventsObserver(MyAdaptyUIOnboardingsEventsObserver())

事件示例（点击展开）

{
    "actionId": "allowNotifications",
    "meta": {
    "onboardingId": "onboarding_123",
    "screenClientId": "profile_screen",
    "screenIndex": 0,
    "screensTotal": 3
}
}

关闭用户引导

当用户点击分配了 Close 操作的按钮时，用户引导即被视为已关闭。您需要管理用户关闭用户引导时所发生的情况。例如：

您需要管理用户关闭用户引导时所发生的情况。例如，您需要停止显示用户引导本身。

如果您使用的是 createNativeOnboardingView，view.isStandaloneView 为 false — 默认实现不会调用 view.dismiss()。请在此回调中将视图从布局中移除，并对其调用 dispose()。

import com.adapty.kmp.AdaptyUI

import com.adapty.kmp.AdaptyUIOnboardingsEventsObserver
import com.adapty.kmp.models.AdaptyUIOnboardingView

import com.adapty.kmp.models.AdaptyUIOnboardingMeta

class MyAdaptyUIOnboardingsEventsObserver : AdaptyUIOnboardingsEventsObserver {
    override fun onboardingViewOnCloseAction(
        view: AdaptyUIOnboardingView,
        meta: AdaptyUIOnboardingMeta,
        actionId: String
    ) {
        // Dismiss the onboarding screen
        mainUiScope.launch {
            view.dismiss()
        }

        // Additional cleanup or navigation logic can be added here
        // For example, navigate back or show main app content
    }
}

// Set up the observer
AdaptyUI.setOnboardingsEventsObserver(MyAdaptyUIOnboardingsEventsObserver())

事件示例（点击展开）

{
    "action_id": "close_button",
    "meta": {
    "onboarding_id": "onboarding_123",
    "screen_cid": "final_screen",
    "screen_index": 3,
    "total_screens": 4
}
}

打开付费墙

如果您希望在用户引导内部打开付费墙，请处理此事件。如果您希望在付费墙关闭后再打开一个付费墙，有一种更直接的方式——处理 onboardingViewOnCloseAction 并在不依赖事件数据的情况下打开付费墙。

如果用户点击了打开付费墙的按钮，您将获得一个手动设置的按钮操作 ID。在用户引导中使用付费墙最无缝的方式，是将操作 ID 设置为与付费墙版位 ID 相同。这样，您就可以直接使用版位 ID 来获取并立即打开付费墙：

import com.adapty.kmp.Adapty

import com.adapty.kmp.AdaptyUI
import com.adapty.kmp.AdaptyUIOnboardingsEventsObserver

import com.adapty.kmp.models.AdaptyUIOnboardingView
import com.adapty.kmp.models.AdaptyUIOnboardingMeta

class MyAdaptyUIOnboardingsEventsObserver : AdaptyUIOnboardingsEventsObserver {
    override fun onboardingViewOnPaywallAction(
        view: AdaptyUIOnboardingView,
        meta: AdaptyUIOnboardingMeta,
        actionId: String
    ) {
        // Get the paywall using the placement ID from the action
        mainUiScope.launch {
            val paywallResult = Adapty.getPaywall(placementId = actionId)
            paywallResult.onSuccess { paywall ->
                val paywallViewResult = AdaptyUI.createPaywallView(paywall)
                paywallViewResult.onSuccess { paywallView ->
                    paywallView.present()
                }.onError { error ->
                    // handle the error
                }
            }.onError { error ->
                // handle the error
            }
        }
    }
}

// Set up the observer
AdaptyUI.setOnboardingsEventsObserver(MyAdaptyUIOnboardingsEventsObserver())

事件示例（点击展开）

{
    "action_id": "premium_offer_1",
    "meta": {
    "onboarding_id": "onboarding_123",
    "screen_cid": "pricing_screen",
    "screen_index": 2,
    "total_screens": 4
}
}

完成用户引导加载

当用户引导完成加载时，将调用此方法：

import com.adapty.kmp.AdaptyUI

import com.adapty.kmp.AdaptyUIOnboardingsEventsObserver
import com.adapty.kmp.models.AdaptyUIOnboardingView

import com.adapty.kmp.models.AdaptyUIOnboardingMeta

class MyAdaptyUIOnboardingsEventsObserver : AdaptyUIOnboardingsEventsObserver {
    override fun onboardingViewDidFinishLoading(
        view: AdaptyUIOnboardingView,
        meta: AdaptyUIOnboardingMeta
    ) {
        // Handle loading completion
        // You can add any initialization logic here
    }
}

// Set up the observer
AdaptyUI.setOnboardingsEventsObserver(MyAdaptyUIOnboardingsEventsObserver())

事件示例（点击展开）

{
    "meta": {
    "onboarding_id": "onboarding_123",
    "screen_cid": "welcome_screen",
    "screen_index": 0,
    "total_screens": 4
}
}

onboardingViewOnAnalyticsEvent 方法在用户引导流程中发生各种分析事件时被调用。 event 对象可以是以下类型之一：

类型	描述
`AdaptyOnboardingsAnalyticsEventOnboardingStarted`	当用户引导加载完成时
`AdaptyOnboardingsAnalyticsEventScreenPresented`	当任意屏幕显示时
`AdaptyOnboardingsAnalyticsEventScreenCompleted`	当某个屏幕完成时。包含可选的 `elementId`（已完成元素的标识符）和可选的 `reply`（用户的回复）。当用户执行任何操作退出该屏幕时触发。
`AdaptyOnboardingsAnalyticsEventSecondScreenPresented`	当第二个屏幕显示时
`AdaptyOnboardingsAnalyticsEventUserEmailCollected`	当用户通过输入框提交邮箱时触发
`AdaptyOnboardingsAnalyticsEventOnboardingCompleted`	当用户到达 ID 为 `final` 的屏幕时触发。如果需要此事件，请将 `final` ID 分配给最后一个屏幕。
`AdaptyOnboardingsAnalyticsEventUnknown`	用于任何无法识别的事件类型。包含 `name`（未知事件的名称）和 `meta`（附加元数据）
每个事件都包含 `meta` 信息，内容如下：

字段	描述
`onboardingId`	用户引导流程的唯一标识符
`screenClientId`	当前屏幕的标识符
`screenIndex`	当前屏幕在流程中的位置
`screensTotal`	流程中的屏幕总数

以下是如何使用分析事件进行追踪的示例：

import com.adapty.kmp.AdaptyUI

import com.adapty.kmp.AdaptyUIOnboardingsEventsObserver
import com.adapty.kmp.models.AdaptyOnboardingsAnalyticsEvent

import com.adapty.kmp.models.AdaptyOnboardingsAnalyticsEventOnboardingCompleted
import com.adapty.kmp.models.AdaptyOnboardingsAnalyticsEventOnboardingStarted

import com.adapty.kmp.models.AdaptyOnboardingsAnalyticsEventScreenCompleted
import com.adapty.kmp.models.AdaptyOnboardingsAnalyticsEventScreenPresented

import com.adapty.kmp.models.AdaptyOnboardingsAnalyticsEventUnknown
import com.adapty.kmp.models.AdaptyUIOnboardingView

import com.adapty.kmp.models.AdaptyUIOnboardingMeta

class MyAdaptyUIOnboardingsEventsObserver : AdaptyUIOnboardingsEventsObserver {
    override fun onboardingViewOnAnalyticsEvent(
        view: AdaptyUIOnboardingView,
        meta: AdaptyUIOnboardingMeta,
        event: AdaptyOnboardingsAnalyticsEvent
    ) {
        when (event) {
            is AdaptyOnboardingsAnalyticsEventOnboardingStarted -> {
                // Track onboarding start
                trackEvent("onboarding_started", event.meta)
            }
            is AdaptyOnboardingsAnalyticsEventScreenPresented -> {
                // Track screen presentation
                trackEvent("screen_presented", event.meta)
            }
            is AdaptyOnboardingsAnalyticsEventScreenCompleted -> {
                // Track screen completion with user response
                trackEvent("screen_completed", event.meta, event.elementId, event.reply)
            }
            is AdaptyOnboardingsAnalyticsEventOnboardingCompleted -> {
                // Track successful onboarding completion
                trackEvent("onboarding_completed", event.meta)
            }
            is AdaptyOnboardingsAnalyticsEventUnknown -> {
                // Handle unknown events
                trackEvent(event.name, event.meta)
            }
            // Handle other cases as needed
        }
    }

    private fun trackEvent(eventName: String, meta: AdaptyUIOnboardingMeta, elementId: String? = null, reply: String? = null) {
        // Implement your analytics tracking here
        // For example, send to your analytics service
    }
}

// Set up the observer
AdaptyUI.setOnboardingsEventsObserver(MyAdaptyUIOnboardingsEventsObserver())

事件示例（点击展开）

// OnboardingStarted
{
    "meta": {
    "onboardingId": "onboarding_123",
    "screenClientId": "welcome_screen",
    "screenIndex": 0,
    "screensTotal": 4
}
}

// ScreenPresented
{
    "meta": {
    "onboardingId": "onboarding_123",
    "screenClientId": "interests_screen",
    "screenIndex": 2,
    "screensTotal": 4
}
}
// ScreenCompleted
{
    "meta": {
    "onboardingId": "onboarding_123",
    "screenClientId": "profile_screen",
    "screenIndex": 1,
    "screensTotal": 4
},
    "elementId": "profile_form",
    "reply": "success"
}

// SecondScreenPresented
{
    "meta": {
    "onboardingId": "onboarding_123",
    "screenClientId": "profile_screen",
    "screenIndex": 1,
    "screensTotal": 4
}
}
// UserEmailCollected
{
    "meta": {
    "onboardingId": "onboarding_123",
    "screenClientId": "profile_screen",
    "screenIndex": 1,
    "screensTotal": 4
}
}

// OnboardingCompleted
{
    "meta": {
    "onboardingId": "onboarding_123",
    "screenClientId": "final_screen",
    "screenIndex": 3,
    "screensTotal": 4
}
}

在 Kotlin Multiplatform SDK 中处理用户引导事件

设置用户引导事件观察者

自定义操作

关闭用户引导

打开付费墙

完成用户引导加载

导航事件