在 Android SDK 中处理用户引导事件

开始之前，请确认：

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

通过编辑工具配置的用户引导会生成各类事件，您的应用可以对这些事件作出响应。请参阅下方说明，了解如何处理这些事件。

如需在 Android 应用中控制或监听用户引导屏幕上发生的操作，请实现 AdaptyOnboardingEventListener 接口。

自定义操作

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

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

class YourActivity : AppCompatActivity() {
    private val eventListener = object : AdaptyOnboardingEventListener {
        override fun onCustomAction(action: AdaptyOnboardingCustomAction, context: Context) {
            when (action.actionId) {
                "allowNotifications" -> {
                    // Request notification permissions
                }
            }
        }
        
        override fun onError(error: AdaptyOnboardingError, context: Context) {
            // Handle errors
        }
        
        // ... other required delegate methods
    }
}

事件示例（点击展开）

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

关闭用户引导

当用户点击分配了 Close 操作的按钮时，用户引导即视为已关闭。你需要处理用户关闭用户引导后的逻辑。例如：

你需要处理用户关闭用户引导后的逻辑，例如停止显示用户引导界面本身。

示例：

override fun onCloseAction(action: AdaptyOnboardingCloseAction, context: Context) {
    // Dismiss the onboarding screen
    (context as? Activity)?.onBackPressed()
}

事件示例（点击展开）

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

打开付费墙

如果你想在用户引导内部打开付费墙，请处理此事件。如果你想在付费墙关闭后再打开另一个付费墙，有一种更直接的方式——处理 AdaptyOnboardingCloseAction 并直接打开付费墙，无需依赖事件数据。

在用户引导中使用付费墙最流畅的方式，是将 action ID 设置为等同于付费墙的版位 ID。这样，在收到 AdaptyOnboardingOpenPaywallAction 事件后，你可以直接用版位 ID 获取并打开对应的付费墙：

override fun onOpenPaywallAction(action: AdaptyOnboardingOpenPaywallAction, context: Context) {
    // Get the paywall using the placement ID from the action
    Adapty.getPaywall(placementId = action.actionId) { result ->
        when (result) {
            is AdaptyResult.Success -> {
                val paywall = result.value
                // Get the paywall configuration
                AdaptyUI.getViewConfiguration(paywall) { result ->
                    when(result) {
                        is AdaptyResult.Success -> {
                            val paywallConfig = result.value
                            // Create and present the paywall
                            val paywallView = AdaptyUI.getPaywallView(
                                activity = this,
                                viewConfig = paywallConfig,
                                products,
                                eventListener = paywallEventListener
                            )
                            // Add the paywall view to your layout
                            binding.container.addView(paywallView)
                        }
                        is AdaptyResult.Error -> {
                            val error = result.error
                            // handle the error
                        }
                    }
                }
            is AdaptyResult.Error -> {
                val error = result.error
                // handle the error
            }        
        }
    }
}

事件示例（点击展开）

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

完成用户引导加载

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

override fun onFinishLoading(action: AdaptyOnboardingLoadedAction, context: Context) {
    // Handle loading completion
}

事件示例（点击展开）

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

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

类型	描述
`OnboardingStarted`	用户引导加载完成时触发
`ScreenPresented`	任意屏幕显示时触发
`ScreenCompleted`	屏幕完成时触发。包含可选的 `elementId`（已完成元素的标识符）和可选的 `reply`（用户的响应）。用户执行任意操作退出屏幕时触发。
`SecondScreenPresented`	第二个屏幕显示时触发
`UserEmailCollected`	通过输入框收集到用户邮箱时触发
`OnboardingCompleted`	用户到达 ID 为 `final` 的屏幕时触发。如需使用此事件，请将最后一个屏幕的 ID 设置为 `final`。
`Unknown`	任何无法识别的事件类型。包含 `name`（未知事件的名称）和 `meta`（附加元数据）
每个事件都包含 `meta` 信息，内容如下：

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

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

override fun onAnalyticsEvent(event: AdaptyOnboardingAnalyticsEvent, context: Context) {
    when (event) {
        is AdaptyOnboardingAnalyticsEvent.OnboardingStarted -> {
            // 追踪用户引导开始
            trackEvent("onboarding_started", event.meta)
        }
        is AdaptyOnboardingAnalyticsEvent.ScreenPresented -> {
            // 追踪屏幕展示
            trackEvent("screen_presented", event.meta)
        }
        is AdaptyOnboardingAnalyticsEvent.ScreenCompleted -> {
            // 追踪屏幕完成及用户响应
            trackEvent("screen_completed", event.meta, event.elementId, event.reply)
        }
        is AdaptyOnboardingAnalyticsEvent.OnboardingCompleted -> {
            // 追踪用户引导成功完成
            trackEvent("onboarding_completed", event.meta)
        }
        is AdaptyOnboardingAnalyticsEvent.Unknown -> {
            // 处理未知事件
            trackEvent(event.name, event.meta)
        }
        // 按需处理其他情况
    }
}

事件示例（点击展开）

// OnboardingStarted
{
  "name": "onboarding_started",
  "meta": {
    "onboarding_id": "onboarding_123",
    "screen_cid": "welcome_screen",
    "screen_index": 0,
    "total_screens": 4
  }
}

// ScreenPresented

{
    "name": "screen_presented",
    "meta": {
        "onboarding_id": "onboarding_123",
        "screen_cid": "interests_screen",
        "screen_index": 2,
        "total_screens": 4
    }
}

// ScreenCompleted

{
    "name": "screen_completed",
    "meta": {
        "onboarding_id": "onboarding_123",
        "screen_cid": "profile_screen",
        "screen_index": 1,
        "total_screens": 4
    },
    "params": {
        "element_id": "profile_form",
        "reply": "success"
    }
}

// SecondScreenPresented

{
    "name": "second_screen_presented",
    "meta": {
        "onboarding_id": "onboarding_123",
        "screen_cid": "profile_screen",
        "screen_index": 1,
        "total_screens": 4
    }
}

// UserEmailCollected

{
    "name": "user_email_collected",
    "meta": {
        "onboarding_id": "onboarding_123",
        "screen_cid": "profile_screen",
        "screen_index": 1,
        "total_screens": 4
    }
}

// OnboardingCompleted

{
    "name": "onboarding_completed",
    "meta": {
        "onboarding_id": "onboarding_123",
        "screen_cid": "final_screen",
        "screen_index": 3,
        "total_screens": 4
    }
}

在 Android SDK 中处理用户引导事件

自定义操作

关闭用户引导

打开付费墙

完成用户引导加载

导航事件