Kotlin Multiplatform SDKでオンボーディングイベントを処理する

始める前に、以下を確認してください：

Adapty Kotlin Multiplatform SDK 3.15.0以降をインストール済みであること。
オンボーディングを作成済みであること。
オンボーディングをプレースメントに追加済みであること。

ビルダーで設定されたオンボーディングは、アプリが応答できるイベントを生成します。これらのイベントへの対応方法について、以下で説明します。

オンボーディングイベントオブザーバーの設定

オンボーディングイベントを処理するには、AdaptyUIOnboardingsEventsObserverインターフェースを実装し、AdaptyUI.setOnboardingsEventsObserver()でセットアップする必要があります。これはアプリのライフサイクルの早い段階、通常はメインアクティビティやアプリの初期化時に行ってください。


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

カスタムアクション

ビルダーでは、ボタンにカスタムアクションを追加してIDを割り当てることができます。このIDをコード内で使用して、カスタムアクションとして処理できます。

たとえば、ユーザーがログインや通知を許可といったカスタムボタンをタップすると、デリゲートメソッドonCustomActionがビルダーで設定したアクションIDとともに呼び出されます。「allowNotifications」のような独自のIDを作成できます。


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

オンボーディングを閉じる

オンボーディングは、ユーザーが閉じるアクションが割り当てられたボタンをタップすると閉じたとみなされます。ユーザーがオンボーディングを閉じたときの動作を管理する必要があります。例：

ユーザーがオンボーディングを閉じたときの動作を管理する必要があります。たとえば、オンボーディング自体の表示を停止する必要があります。

createNativeOnboardingViewを使用している場合、view.isStandaloneViewがfalseのとき、デフォルトの実装ではview.dismiss()は呼び出されません。このコールバック内でビューをレイアウトから削除し、dispose()を呼び出してください。


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を使ってすぐにペイウォールを取得して開くことができます：


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

オンボーディングの読み込み完了

オンボーディングの読み込みが完了すると、このメソッドが呼び出されます：


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`	2番目の画面が表示されたとき
`AdaptyOnboardingsAnalyticsEventUserEmailCollected`	入力フィールドでユーザーのメールアドレスが収集されたときにトリガーされる
`AdaptyOnboardingsAnalyticsEventOnboardingCompleted`	ユーザーが`final` IDを持つ画面に到達したときにトリガーされる。このイベントが必要な場合は、最後の画面に`final` IDを割り当てる。
`AdaptyOnboardingsAnalyticsEventUnknown`	認識されないイベントタイプの場合。`name`（不明なイベントの名前）と`meta`（追加のメタデータ）を含む。

各イベントには以下のmeta情報が含まれます：

フィールド	説明
`onboardingId`	オンボーディングフローの一意の識別子
`screenClientId`	現在の画面の識別子
`screenIndex`	フロー内の現在の画面の位置
`screensTotal`	フロー内の画面の総数

アナリティクスイベントをトラッキングに使用する例：


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でオンボーディングイベントを処理する

オンボーディングイベントオブザーバーの設定

カスタムアクション

オンボーディングを閉じる

ペイウォールを開く

オンボーディングの読み込み完了

ナビゲーションイベント