---
title: "Обработка событий онбординга в Unity SDK"
description: "Обрабатывайте события, связанные с онбордингом, в Unity с помощью Adapty."
---

Перед началом убедитесь, что:

1. Вы установили [Adapty Unity SDK](sdk-installation-unity) версии 3.14.0 или новее.
2. Вы [создали онбординг](create-onboarding).
3. Вы добавили онбординг в [плейсмент](placements).

Онбординги, настроенные с помощью билдера, генерируют события, на которые может реагировать ваше приложение. Ниже описано, как с ними работать.

Чтобы контролировать или отслеживать процессы, происходящие на экране онбординга в вашем Unity-приложении, реализуйте интерфейс `AdaptyOnboardingsEventsListener`.

## Пользовательские действия \{#custom-actions\}

В билдере вы можете добавить **пользовательское** действие к кнопке и назначить ему 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 */
  }}
/>

Затем вы можете использовать этот ID в своём коде и обрабатывать его как пользовательское действие. Например, если пользователь нажимает пользовательскую кнопку, такую как **Login** или **Allow notifications**, будет вызван метод `OnboardingViewOnCustomAction` с параметром `actionId`, равным **Action ID** из билдера. Вы можете создавать собственные ID, например «allowNotifications».

Чтобы обрабатывать события онбординга, реализуйте интерфейс `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>Пример события (нажмите, чтобы развернуть)</summary>

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

## Закрытие онбординга \{#closing-onboarding\}

Онбординг считается закрытым, когда пользователь нажимает кнопку с назначенным действием **Close**.

  <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
Обратите внимание, что вам нужно самостоятельно управлять тем, что происходит при закрытии онбординга пользователем. Например, необходимо прекратить отображение самого онбординга.
:::

Реализуйте метод `OnboardingViewOnCloseAction` в своём классе:

```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>Пример события (нажмите, чтобы развернуть)</summary>

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

</Details>

## Открытие пейвола \{#opening-a-paywall\}

:::tip
Обрабатывайте это событие, если хотите открыть пейвол внутри онбординга. Если вы хотите открыть пейвол после закрытия онбординга, есть более простой способ — обработайте [`OnboardingViewOnCloseAction`](#closing-onboarding) и откройте пейвол, не опираясь на данные события.
:::

Если пользователь нажимает кнопку, открывающую пейвол, вы получите ID действия кнопки, который вы [задали вручную](get-paid-in-onboardings). Наиболее удобный способ работы с пейволами в онбордингах — сделать ID действия равным ID плейсмента пейвола. Тогда после события `OnboardingViewOnPaywallAction` вы сможете сразу использовать ID плейсмента для получения и отображения пейвола.

Обратите внимание, что в iOS одновременно на экране может отображаться только одно представление (пейвол или онбординг). Если вы показываете пейвол поверх онбординга, вы не можете программно управлять онбордингом в фоне. Попытка закрыть онбординг закроет пейвол, оставив онбординг видимым. Чтобы избежать этого, всегда закрывайте представление онбординга перед показом пейвола.

```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>Пример события (нажмите, чтобы развернуть)</summary>

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

</Details>

## Завершение загрузки онбординга \{#finishing-loading-onboarding\}

Когда онбординг завершает загрузку, реализуйте метод `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>Пример события (нажмите, чтобы развернуть)</summary>

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

</Details>

## Отслеживание навигации \{#tracking-navigation\}

Метод `OnboardingViewOnAnalyticsEvent` вызывается при возникновении различных аналитических событий в процессе онбординга.

Объект `analyticsEvent` может быть одного из следующих типов:
| Тип | Описание |
|------------|-------------|
| `AdaptyOnboardingsAnalyticsEventOnboardingStarted` | Когда онбординг загружен |
| `AdaptyOnboardingsAnalyticsEventScreenPresented` | Когда отображается любой экран |
| `AdaptyOnboardingsAnalyticsEventScreenCompleted` | Когда экран завершён. Включает необязательный `ElementId` (идентификатор завершённого элемента) и необязательный `Reply` (ответ пользователя). Срабатывает, когда пользователь выполняет любое действие для выхода с экрана. |
| `AdaptyOnboardingsAnalyticsEventSecondScreenPresented` | Когда показывается второй экран |
| `AdaptyOnboardingsAnalyticsEventUserEmailCollected` | Срабатывает, когда email пользователя собирается через поле ввода |
| `AdaptyOnboardingsAnalyticsEventOnboardingCompleted` | Срабатывает, когда пользователь достигает экрана с ID `final`. Если вам нужно это событие, [назначьте ID `final` последнему экрану](design-onboarding). |
| `AdaptyOnboardingsAnalyticsEventUnknown` | Для любого нераспознанного типа события. Включает `Name` (название неизвестного события) и `meta` (дополнительные метаданные) |

Каждое событие содержит информацию `meta` со следующими полями:
| Поле | Описание |
|------------|-------------|
| `OnboardingId` | Уникальный идентификатор онбординга |
| `ScreenClientId` | Идентификатор текущего экрана |
| `ScreenIndex` | Позиция текущего экрана в потоке |
| `ScreensTotal` | Общее количество экранов в потоке |

Вот пример использования аналитических событий для отслеживания:

```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
Метод `TrackEvent` — это заглушка, которую вам нужно реализовать самостоятельно для отправки аналитики в предпочитаемый вами аналитический сервис.
:::

<Details>
<summary>Примеры событий (нажмите, чтобы развернуть)</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>