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

オンボーディングはSDK v4で非推奨となり、将来のリリースで削除される予定です。 バグ修正や機能改善は行われません。代わりにフローを使用してください。オンボーディングはWebView内で動作しますが、フローはデバイス上でネイティブにレンダリングされるため、よりスムーズなアニメーション、一貫したネイティブの外観、高速な読み込み、WebViewランタイムへの依存がなくなります。まずはフロー＆ペイウォールの取得とフロー＆ペイウォールの表示をご覧ください。

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

Adapty Kotlin Multiplatform SDK 3.15.0 以降がインストールされている。
オンボーディングを作成している。
オンボーディングをプレースメントに追加している。

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

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

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


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

カスタムアクション

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

例えば、ユーザーが Login や Allow notifications などのカスタムボタンをタップすると、デリゲートメソッド 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
}
}

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

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

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

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

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

カスタムアクション

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

ペイウォールを開く

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

ナビゲーションイベント