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

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

1. Bạn đã cài đặt [Adapty Unity SDK](sdk-installation-unity) phiên bản 3.14.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. Hãy xem 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 diễn ra trên màn hình onboarding trong ứng dụng Unity của bạn, hãy triển khai interface `AdaptyOnboardingsEventsListener`.

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

Trong builder, bạn có thể thêm hành động **custom** cho một nút và gán cho nó một ID.

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

Sau đó, bạn có thể sử dụng ID này trong code và xử lý nó như một hành động tùy chỉnh. 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 `OnboardingViewOnCustomAction` sẽ được kích hoạt với tham số `actionId` là **Action ID** từ builder. Bạn có thể tự tạo ID theo ý muốn, ví dụ như "allowNotifications".

Để xử lý các sự kiện onboarding, hãy triển khai interface `AdaptyOnboardingsEventsListener`:

```csharp showLineNumbers title="Unity"
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)
}
```

<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 một nút có hành động **Close** được gán.

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

:::important
Lưu ý rằng bạn cần tự quản lý điều gì xảy ra khi người dùng đóng onboarding. Ví dụ: bạn cần dừng hiển thị chính onboarding đó.
:::

Triển khai phương thức `OnboardingViewOnCloseAction` trong class của bạn:

```csharp showLineNumbers title="Unity"
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
}
```

<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ở paywall \{#opening-a-paywall\}

:::tip
Hãy xử lý sự kiện này để mở paywall nếu bạn muốn hiển thị 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ý [`OnboardingViewOnCloseAction`](#closing-onboarding) và mở paywall mà không cần dựa vào dữ liệu sự kiện.
:::

Cách làm liền mạch nhất khi 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 `OnboardingViewOnPaywallAction`, bạn có thể dùng placement ID để lấy và mở paywall ngay lập tức.

Lưu ý rằng, trên iOS, chỉ có thể hiển thị một view (paywall hoặc onboarding) trên màn hình tại một thời điểm. Nếu bạn hiển thị paywall chồng lên onboarding, bạn không thể kiểm soát onboarding ở nền theo cách lập trình. Nếu cố dismiss onboarding, paywall sẽ bị đóng thay vào đó, khiến onboarding vẫn còn hiển thị. Để tránh điều này, hãy luôn dismiss view onboarding trước khi hiển thị paywall.

```csharp showLineNumbers title="Unity"
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
}
```

<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 tất tải onboarding \{#finishing-loading-onboarding\}

Khi onboarding tải xong, hãy triển khai phương thức `OnboardingViewDidFinishLoading`:

```csharp showLineNumbers title="Unity"
public class OnboardingManager : MonoBehaviour, AdaptyOnboardingsEventsListener
{
    public void OnboardingViewDidFinishLoading(
        AdaptyUIOnboardingView view,
        AdaptyUIOnboardingMeta meta
    )
    {
        // handle loading completion
    }
    
    // ... other interface methods
}
```

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

## Theo dõi điều hướng \{#tracking-navigation\}

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

Đối tượng `analyticsEvent` có thể là một trong các kiểu sau:
| Kiểu | Mô tả |
|------------|-------------|
| `AdaptyOnboardingsAnalyticsEventOnboardingStarted` | Khi onboarding đã được tải |
| `AdaptyOnboardingsAnalyticsEventScreenPresented` | Khi bất kỳ màn hình nào được hiển thị |
| `AdaptyOnboardingsAnalyticsEventScreenCompleted` | Khi một màn hình hoàn tất. Bao gồm `ElementId` tùy chọn (định danh của phần tử đã hoàn tất) 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. |
| `AdaptyOnboardingsAnalyticsEventSecondScreenPresented` | Khi màn hình thứ hai được hiển thị |
| `AdaptyOnboardingsAnalyticsEventUserEmailCollected` | Được kích hoạt khi email của người dùng được thu thập qua trường nhập liệu |
| `AdaptyOnboardingsAnalyticsEventOnboardingCompleted` | Đượ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](design-onboarding). |
| `AdaptyOnboardingsAnalyticsEventUnknown` | 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 |
| `ScreensTotal` | Tổng số màn hình trong flow |

Dưới đây là ví dụ về cách sử dụng sự kiện analytics để theo dõi:

```csharp showLineNumbers title="Unity"
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
}
```

:::note
Phương thức `TrackEvent` là một placeholder mà bạn cần tự triển khai để gửi analytics đến dịch vụ analytics mà bạn muốn sử dụng.
:::

<Details>
<summary>Ví dụ 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>