Обработка событий онбординга в Flutter SDK

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

  • Полноэкранное представление: Требует настройки глобального наблюдателя событий, который обрабатывает события для всех экранов онбординга
  • Встроенный виджет: Обрабатывает события через inline-параметры обратного вызова непосредственно в виджете

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

  1. Вы установили Adapty Flutter SDK версии 3.8.0 или новее.
  2. Вы создали онбординг.
  3. Вы добавили онбординг в плейсмент.

События полноэкранного отображения

Настройка наблюдателя событий

Чтобы обрабатывать события для полноэкранных онбордингов, реализуйте AdaptyUIOnboardingsEventsObserver и установите его перед отображением:

AdaptyUI().setOnboardingsEventsObserver(this);

try {
  await onboardingView.present();
} on AdaptyError catch (e) {
  // handle the error
} catch (e) {
  // handle the error
}

Обработка событий

Реализуйте следующие методы в вашем обработчике:

void onboardingViewDidFinishLoading(
  AdaptyUIOnboardingView view,
  AdaptyUIOnboardingMeta meta,
) {
  // Онбординг завершил загрузку
}

void onboardingViewDidFailWithError(
  AdaptyUIOnboardingView view,
  AdaptyError error,
) {
  // Обработка ошибок загрузки
}

void onboardingViewOnCloseAction(
  AdaptyUIOnboardingView view,
  AdaptyUIOnboardingMeta meta,
  String actionId,
) {
  // Обработка действия закрытия
  view.dismiss();
}

void onboardingViewOnPaywallAction(
  AdaptyUIOnboardingView view,
  AdaptyUIOnboardingMeta meta,
  String actionId,
) {
  // Закрыть онбординг перед показом пейвола
  view.dismiss().then((_) {
    _openPaywall(actionId);
  });
}

void onboardingViewOnCustomAction(
  AdaptyUIOnboardingView view,
  AdaptyUIOnboardingMeta meta,
  String actionId,
) {
  // Обработка пользовательских действий
}

void onboardingViewOnStateUpdatedAction(
  AdaptyUIOnboardingView view,
  AdaptyUIOnboardingMeta meta,
  String elementId,
  AdaptyOnboardingsStateUpdatedParams params,
) {
  // Обработка обновлений пользовательского ввода
}

void onboardingViewOnAnalyticsEvent(
  AdaptyUIOnboardingView view,
  AdaptyUIOnboardingMeta meta,
  AdaptyOnboardingsAnalyticsEvent event,
) {
  // Отслеживание аналитических событий
}

События встроенного виджета

При использовании AdaptyUIOnboardingPlatformView вы можете обрабатывать события через встроенные параметры обратного вызова непосредственно в виджете. Обратите внимание, что события отправляются как в колбэки виджета, так и в глобальный наблюдатель (если он настроен), однако глобальный наблюдатель необязателен:

AdaptyUIOnboardingPlatformView(
  onboarding: onboarding,
  onDidFinishLoading: (meta) {
    // Onboarding finished loading
  },
  onDidFailWithError: (error) {
    // Handle loading errors
  },
  onCloseAction: (meta, actionId) {
    // Handle close action
  },
  onPaywallAction: (meta, actionId) {
    _openPaywall(actionId);
  },
  onCustomAction: (meta, actionId) {
    // Handle custom actions
  },
  onStateUpdatedAction: (meta, elementId, params) {
    // Handle user input updates
  },
  onAnalyticsEvent: (meta, event) {
    // Track analytics events
  },
)

Типы событий

В следующих разделах описаны различные типы событий, которые можно обрабатывать независимо от выбранного подхода к отображению.

Обработка пользовательских действий

В конструкторе вы можете добавить пользовательское действие к кнопке и назначить ему идентификатор.

ios-events-1.webp

Затем этот ID можно использовать в коде и обрабатывать как пользовательское действие. Например, если пользователь нажимает кастомную кнопку — Login или Allow notifications — сработает метод делегата onboardingController с кейсом .custom(id:), а параметр actionId будет равен Action ID из билдера. Вы можете создавать собственные ID, например "allowNotifications".

// Full-screen presentation
void onboardingViewOnCustomAction(
    AdaptyUIOnboardingView view,
    AdaptyUIOnboardingMeta meta,
    String actionId,
) {
    switch (actionId) {
        case 'login':
            _login();
            break;
        case 'allow_notifications':
            _allowNotifications();
            break;
    }
}

// Embedded widget
onCustomAction: (meta, actionId) {
    _handleCustomAction(actionId);
}
Пример события (нажмите, чтобы развернуть)
{
  "actionId": "allowNotifications",
  "meta": {
    "onboardingId": "onboarding_123",
    "screenClientId": "profile_screen",
    "screenIndex": 0,
    "screensTotal": 3
  }
}

Завершение загрузки онбординга

Когда онбординг заканчивает загрузку, срабатывает это событие:

// Full-screen presentation
void onboardingViewDidFinishLoading(
  AdaptyUIOnboardingView view,
  AdaptyUIOnboardingMeta meta,
) {
  print('Onboarding loaded: ${meta.onboardingId}');
}

// Embedded widget
onDidFinishLoading: (meta) {
  print('Onboarding loaded: ${meta.onboardingId}');
}
Пример события (нажмите, чтобы раскрыть)
{
    "meta": {
        "onboarding_id": "onboarding_123",
        "screen_cid": "welcome_screen",
        "screen_index": 0,
        "total_screens": 4
    }
}

Закрытие онбординга

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

ios-events-2.webp

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

// Full-screen presentation
void onboardingViewOnCloseAction(
  AdaptyUIOnboardingView view,
  AdaptyUIOnboardingMeta meta,
  String actionId,
) {
  await view.dismiss();
}

// Embedded widget
onCloseAction: (meta, actionId) {
  Navigator.of(context).pop();
}
Пример события (нажмите, чтобы раскрыть)
{
  "action_id": "close_button",
  "meta": {
    "onboarding_id": "onboarding_123",
    "screen_cid": "final_screen",
    "screen_index": 3,
    "total_screens": 4
  }
}

Открытие пейвола

Обрабатывайте это событие, чтобы открыть пейвол внутри онбординга. Если вы хотите открыть пейвол после его закрытия, есть более простой способ — обработать действие закрытия и открыть пейвол, не полагаясь на данные события.

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

// Full-screen presentation
void onboardingViewOnPaywallAction(
  AdaptyUIOnboardingView view,
  AdaptyUIOnboardingMeta meta,
  String actionId,
) {
  // Dismiss onboarding before presenting paywall
  view.dismiss().then((_) {
    _openPaywall(actionId);
  });
}

Future<void> _openPaywall(String actionId) async {
  // Implement your paywall opening logic here
}

// Embedded widget
onPaywallAction: (meta, actionId) {
  _openPaywall(actionId);
}
Пример события (нажмите, чтобы развернуть)
{
    "action_id": "premium_offer_1",
    "meta": {
        "onboarding_id": "onboarding_123",
        "screen_cid": "pricing_screen",
        "screen_index": 2,
        "total_screens": 4
    }
}

Отслеживание навигации

Аналитическое событие поступает при различных навигационных событиях в онбординге:

// Full-screen presentation
void onboardingViewOnAnalyticsEvent(
  AdaptyUIOnboardingView view,
  AdaptyUIOnboardingMeta meta,
  AdaptyOnboardingsAnalyticsEvent event,
) {
  trackEvent(event.type, meta.onboardingId);
}

// Embedded widget
onAnalyticsEvent: (meta, event) {
  trackEvent(event.type, meta.onboardingId);
}

Объект event может быть одного из следующих типов:

ТипОписание
onboardingStartedКогда онбординг загружен
screenPresentedКогда показан любой экран
screenCompletedКогда экран завершён. Включает необязательный elementId (идентификатор завершённого элемента) и необязательный reply (ответ пользователя). Срабатывает, когда пользователь выполняет любое действие для выхода с экрана.
secondScreenPresentedКогда показан второй экран
userEmailCollectedСрабатывает, когда email пользователя собран через поле ввода
onboardingCompletedСрабатывает, когда пользователь достигает экрана с идентификатором final. Если вам нужно это событие, назначьте идентификатор final последнему экрану.
unknownДля любого нераспознанного типа события. Включает name (название неизвестного события) и meta (дополнительные метаданные)
Каждое событие содержит meta-информацию:
ПолеОписание
onboardingIdУникальный идентификатор флоу онбординга
screenClientIdИдентификатор текущего экрана
screenIndexПозиция текущего экрана в флоу
screensTotalОбщее количество экранов во флоу
Примеры событий (нажмите, чтобы развернуть)
// 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
    }
}