---
title: "Xử lý sự kiện onboarding trong Android SDK"
description: "Xử lý các sự kiện liên quan đến onboarding trong Android bằng Adapty."
---

Trước khi bắt đầu, hãy đảm bảo rằng:

1. Bạn đã cài đặt [Adapty Android SDK](sdk-installation-android) phiên bản 3.8.0 trở lên.
2. Bạn đã [tạo một onboarding](create-onboarding).
3. Bạn đã thêm onboarding vào một [placement](placements).

Các onboarding được cấu hình bằng builder sẽ tạo ra các sự kiện mà ứng dụng của bạn có thể phản hồi. Tìm hiểu cách xử lý các sự kiện này bên dưới.

Để kiểm soát hoặc theo dõi các tiến trình xảy ra trên màn hình onboarding trong ứng dụng Android của bạn, hãy implement interface `AdaptyOnboardingEventListener`.

## Hành động tùy chỉnh \{#custom-actions\}

Trong builder, bạn có thể thêm hành động **tùy chỉnh** cho một nút và gán cho nó một ID. Sau đó, bạn có thể dùng ID này trong code và xử lý nó như một hành động tùy chỉnh.

  <img src="/assets/shared/img/ios-events-1.webp"
  style={{
    border: '1px solid #727272', /* border width and color */
    width: '700px', /* image width */
    display: 'block', /* for alignment */
    margin: '0 auto' /* center alignment */
  }}
/>

Ví dụ: nếu người dùng nhấn vào một nút tùy chỉnh như **Login** hoặc **Allow notifications**, phương thức delegate `onCustomAction` sẽ được kích hoạt với action ID từ builder. Bạn có thể tự tạo ID, chẳng hạn như "allowNotifications".

```kotlin showLineNumbers
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
    }
}
```

<Details>
<summary>Ví dụ sự kiện (Nhấn để mở rộng)</summary>

```json
{
  "actionId": "allowNotifications",
  "meta": {
    "onboardingId": "onboarding_123",
    "screenClientId": "profile_screen",
    "screenIndex": 0,
    "screensTotal": 3
  }
}
```
</Details>

## Đóng onboarding \{#closing-onboarding\}

Onboarding được coi là đã đóng khi người dùng nhấn vào nút được gán hành động **Close**. Bạn cần quản lý những gì xảy ra khi người dùng đóng onboarding. Ví dụ:

:::important
Bạn cần quản lý những gì xảy ra khi người dùng đóng onboarding. Chẳng hạn, bạn cần dừng hiển thị chính onboarding đó.
:::

Ví dụ:

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

<Details>
<summary>Ví dụ sự kiện (Nhấn để mở rộng)</summary>

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

</Details>

## Mở một paywall \{#opening-a-paywall\}

:::tip
Xử lý sự kiện này để mở paywall nếu bạn muốn mở nó bên trong onboarding. Nếu bạn muốn mở paywall sau khi onboarding đã đóng, có một cách đơn giản hơn — xử lý [`AdaptyOnboardingCloseAction`](#closing-onboarding) và mở paywall mà không cần dựa vào dữ liệu sự kiện.
:::

Cách liền mạch nhất để làm việc với paywall trong onboarding là đặt action ID bằng với placement ID của paywall. Như vậy, sau sự kiện `AdaptyOnboardingOpenPaywallAction`, bạn có thể dùng placement ID để lấy và mở paywall ngay lập tức:

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

<Details>
<summary>Ví dụ sự kiện (Nhấn để mở rộng)</summary>

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

</Details>

## Hoàn thành tải onboarding \{#finishing-loading-onboarding\}

Khi onboarding hoàn tất quá trình tải, phương thức này sẽ được gọi:

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

<Details>
<summary>Ví dụ sự kiện (Nhấn để mở rộng)</summary>

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

</Details>

## Sự kiện điều hướng \{#navigation-events\}

Phương thức `onAnalyticsEvent` được gọi khi các sự kiện analytics khác nhau xảy ra trong flow onboarding.

Đối tượng `event` có thể là một trong các loại sau:
|Loại | Mô tả |
|------------|-------------|
| `OnboardingStarted` | Khi onboarding đã được tải |
| `ScreenPresented` | Khi bất kỳ màn hình nào được hiển thị |
| `ScreenCompleted` | Khi một màn hình hoàn thành. Bao gồm `elementId` tùy chọn (định danh của phần tử đã hoàn thành) và `reply` tùy chọn (phản hồi từ người dùng). Được kích hoạt khi người dùng thực hiện bất kỳ hành động nào để thoát khỏi màn hình. |
| `SecondScreenPresented` | Khi màn hình thứ hai được hiển thị |
| `UserEmailCollected` | Được kích hoạt khi email của người dùng được thu thập qua trường nhập liệu |
| `OnboardingCompleted` | Được kích hoạt khi người dùng đến màn hình có ID `final`. Nếu bạn cần sự kiện này, hãy gán ID `final` cho màn hình cuối cùng. |
| `Unknown` | Cho bất kỳ loại sự kiện nào không được nhận dạng. Bao gồm `name` (tên của sự kiện không xác định) và `meta` (metadata bổ sung) |

Mỗi sự kiện bao gồm thông tin `meta` chứa:
| Trường | Mô tả |
|------------|-------------|
| `onboardingId` | Định danh duy nhất của flow onboarding |
| `screenClientId` | Định danh của màn hình hiện tại |
| `screenIndex` | Vị trí của màn hình hiện tại trong flow |
| `totalScreens` | Tổng số màn hình trong flow |

Đây là ví dụ về cách bạn có thể sử dụng các sự kiện analytics để theo dõi:

```kotlin
override fun onAnalyticsEvent(event: AdaptyOnboardingAnalyticsEvent, context: Context) {
    when (event) {
        is AdaptyOnboardingAnalyticsEvent.OnboardingStarted -> {
            // Track onboarding start
            trackEvent("onboarding_started", event.meta)
        }
        is AdaptyOnboardingAnalyticsEvent.ScreenPresented -> {
            // Track screen presentation
            trackEvent("screen_presented", event.meta)
        }
        is AdaptyOnboardingAnalyticsEvent.ScreenCompleted -> {
            // Track screen completion with user response
            trackEvent("screen_completed", event.meta, event.elementId, event.reply)
        }
        is AdaptyOnboardingAnalyticsEvent.OnboardingCompleted -> {
            // Track successful onboarding completion
            trackEvent("onboarding_completed", event.meta)
        }
        is AdaptyOnboardingAnalyticsEvent.Unknown -> {
            // Handle unknown events
            trackEvent(event.name, event.meta)
        }
        // Handle other cases as needed
    }
}
``` 

<Details>
<summary>Ví dụ các sự kiện (Nhấn để mở rộng)</summary>

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

```

</Details>