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

在开始之前，请确保：

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

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

要在 Unity 应用中控制或监控用户引导界面上发生的流程，请实现 AdaptyOnboardingsEventsListener 接口。

自定义动作

在编辑工具中，您可以为按钮添加自定义动作并为其分配一个 ID。

然后，您可以在代码中使用此 ID 并将其作为自定义动作处理。例如，当用户点击自定义按钮（如登录或允许通知）时，将触发 OnboardingViewOnCustomAction 方法，其中 actionId 参数为编辑工具中的 Action ID。您可以创建自己的 ID，例如 “allowNotifications”。

要处理用户引导事件，请实现 AdaptyOnboardingsEventsListener 接口：

public class OnboardingManager : MonoBehaviour, AdaptyOnboardingsEventsListener
{
    void Start()
    {
        Adapty.SetOnboardingsEventsListener(this);
    }

    public void OnboardingViewOnCustomAction(
        AdaptyUIOnboardingView view,
        AdaptyUIOnboardingMeta meta,
        string actionId
    )
    {
        if (actionId == "allowNotifications") {
            // request notification permissions
        }
    }
    
    public void OnboardingViewDidFailWithError(
        AdaptyUIOnboardingView view,
        AdaptyError error
    )
    {
        // handle errors
    }

    // Implement other required interface methods (see examples below)
}

事件示例（点击展开）

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

关闭用户引导

当用户点击分配了关闭动作的按钮时，用户引导即被视为已关闭。

请注意，您需要自行管理用户关闭用户引导后发生的事情。例如，您需要停止显示用户引导本身。

在您的类中实现 OnboardingViewOnCloseAction 方法：

public class OnboardingManager : MonoBehaviour, AdaptyOnboardingsEventsListener
{
    public void OnboardingViewOnCloseAction(
        AdaptyUIOnboardingView view,
        AdaptyUIOnboardingMeta meta,
        string actionId
    )
    {
        view.Dismiss((error) => {
            if (error != null) {
                // handle the error
            }
        });
    }
    
    // ... other interface methods
}

事件示例（点击展开）

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

打开付费墙

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

如果用户点击打开付费墙的按钮，您将获得您手动设置的按钮动作 ID。在用户引导中使用付费墙最无缝的方式是将动作 ID 设置为等于付费墙版位 ID。这样，在 OnboardingViewOnPaywallAction 之后，您可以立即使用版位 ID 获取并打开付费墙。

请注意，在 iOS 上，屏幕上一次只能显示一个视图（付费墙或用户引导）。如果您在用户引导上叠加显示付费墙，则无法以编程方式控制后台的用户引导。尝试关闭用户引导将会关闭付费墙，导致用户引导仍然可见。为避免这种情况，请始终在显示付费墙之前先关闭用户引导视图。

public class OnboardingManager : MonoBehaviour, AdaptyOnboardingsEventsListener
{
    public void OnboardingViewOnPaywallAction(
        AdaptyUIOnboardingView view,
        AdaptyUIOnboardingMeta meta,
        string actionId
    )
    {
        // Dismiss onboarding before presenting paywall
        view.Dismiss((dismissError) => {
            if (dismissError != null) {
                // handle the error
                return;
            }

            Adapty.GetPaywall(actionId, (paywall, error) => {
                if (error != null) {
                    // handle the error
                    return;
                }

                AdaptyUI.CreatePaywallView(paywall, (paywallView, createError) => {
                    if (createError != null) {
                        // handle the error
                        return;
                    }

                    paywallView.Present((presentError) => {
                        if (presentError != null) {
                            // handle the error
                        }
                    });
                });
            });
        });
    }
    
    // ... other interface methods
}

事件示例（点击展开）

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

完成用户引导加载

当用户引导加载完成时，实现 OnboardingViewDidFinishLoading 方法：

public class OnboardingManager : MonoBehaviour, AdaptyOnboardingsEventsListener
{
    public void OnboardingViewDidFinishLoading(
        AdaptyUIOnboardingView view,
        AdaptyUIOnboardingMeta meta
    )
    {
        // handle loading completion
    }
    
    // ... other interface methods
}

事件示例（点击展开）

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

OnboardingViewOnAnalyticsEvent 方法在用户引导流程中发生各种分析事件时被调用。

analyticsEvent 对象可以是以下类型之一：

类型	描述
`AdaptyOnboardingsAnalyticsEventOnboardingStarted`	用户引导已加载时
`AdaptyOnboardingsAnalyticsEventScreenPresented`	任何屏幕显示时
`AdaptyOnboardingsAnalyticsEventScreenCompleted`	屏幕完成时。包含可选的 `ElementId`（已完成元素的标识符）和可选的 `Reply`（用户的响应）。当用户执行任何操作退出屏幕时触发。
`AdaptyOnboardingsAnalyticsEventSecondScreenPresented`	第二个屏幕显示时
`AdaptyOnboardingsAnalyticsEventUserEmailCollected`	通过输入字段收集用户邮箱时触发
`AdaptyOnboardingsAnalyticsEventOnboardingCompleted`	当用户到达具有 `final` ID 的屏幕时触发。如果您需要此事件，请将 `final` ID 分配给最后一个屏幕。
`AdaptyOnboardingsAnalyticsEventUnknown`	用于任何无法识别的事件类型。包含 `Name`（未知事件的名称）和 `meta`（附加元数据）

每个事件都包含 meta 信息：

字段	描述
`OnboardingId`	用户引导流程的唯一标识符
`ScreenClientId`	当前屏幕的标识符
`ScreenIndex`	当前屏幕在流程中的位置
`ScreensTotal`	流程中的屏幕总数

以下是如何将分析事件用于追踪的示例：

public class OnboardingManager : MonoBehaviour, AdaptyOnboardingsEventsListener
{
    public void OnboardingViewOnAnalyticsEvent(
        AdaptyUIOnboardingView view,
        AdaptyUIOnboardingMeta meta,
        AdaptyOnboardingsAnalyticsEvent analyticsEvent
    )
    {
        switch (analyticsEvent) {
            case AdaptyOnboardingsAnalyticsEventOnboardingStarted:
                // track onboarding start
                TrackEvent("onboarding_started", meta);
                break;
            case AdaptyOnboardingsAnalyticsEventScreenPresented:
                // track screen presentation
                TrackEvent("screen_presented", meta);
                break;
            case AdaptyOnboardingsAnalyticsEventScreenCompleted screenCompleted:
                // track screen completion with user response
                TrackEvent("screen_completed", meta, screenCompleted.ElementId, screenCompleted.Reply);
                break;
            case AdaptyOnboardingsAnalyticsEventOnboardingCompleted:
                // track successful onboarding completion
                TrackEvent("onboarding_completed", meta);
                break;
            case AdaptyOnboardingsAnalyticsEventUnknown unknownEvent:
                // handle unknown events
                TrackEvent(unknownEvent.Name, meta);
                break;
            // handle other cases as needed
        }
    }
    
    // ... other interface methods
}

TrackEvent 方法是一个占位符，您需要自行实现它以将分析数据发送到您首选的分析服务。

事件示例（点击展开）

// 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
    }
}

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

自定义动作

关闭用户引导

打开付费墙

完成用户引导加载

追踪导航