English 中文TürkçeРусскийEspañol日本語Tiếng ViệtFrançais

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

Онбординги объявлены устаревшими в SDK v4 и будут удалены в одном из следующих релизов. Они больше не получают исправлений и улучшений. Используйте флоу: в отличие от онбордингов, которые работают внутри WebView, флоу рендерятся нативно на устройстве — обеспечивая более плавные анимации, единый нативный внешний вид, быструю загрузку и отсутствие зависимости от WebView. Подробнее: Получение флоу и пейволов и Отображение флоу и пейволов.

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

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

  1. Вы создали онбординг.
  2. Вы добавили онбординг в плейсмент.

Настройка обработчиков событий

Для обработки событий онбордингов используйте метод view.setEventHandlers:


try {
  const view = await createOnboardingView(onboarding);
  
  view.setEventHandlers({
    onAnalytics(event, meta) {
      console.log('Analytics event:', event);
    },
    onClose(actionId, meta) {
      console.log('Onboarding closed:', actionId);
      return true; // Allow the onboarding to close
    },
    onCustom(actionId, meta) {
      console.log('Custom action:', actionId);
      return false; // Don't close the onboarding
    },
    onPaywall(actionId, meta) {
      console.log('Paywall action:', actionId);
      view.dismiss().then(() => {
        openPaywall(actionId);
      });
    },
    onStateUpdated(action, meta) {
      console.log('State updated:', action);
    },
    onFinishedLoading(meta) {
      console.log('Onboarding finished loading');
    },
    onError(error) {
      console.error('Onboarding error:', error);
    },
  });
  
  await view.present();
} catch (error) {
  console.error('Failed to present onboarding:', error);
}

Типы событий

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

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

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

ios-events-1.webp

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

view.setEventHandlers({
  onCustom(actionId, meta) {
    switch (actionId) {
      case 'login':
        console.log('Login action triggered');
        break;
      case 'allow_notifications':
        console.log('Allow notifications action triggered');
        break;
    }
    return false; // Don't close the onboarding
  },
});
Пример события (нажмите, чтобы развернуть)
{
  "actionId": "allow_notifications",
  "meta": {
    "onboardingId": "onboarding_123",
    "screenClientId": "profile_screen",
    "screenIndex": 0,
    "screensTotal": 3
  }
}

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

Когда онбординг завершает загрузку, срабатывает следующее событие:

view.setEventHandlers({
  onFinishedLoading(meta) {
    console.log('Onboarding loaded:', meta.onboardingId);
  },
});
Пример события (нажмите, чтобы развернуть)
{
    "meta": {
        "onboarding_id": "onboarding_123",
        "screen_cid": "welcome_screen",
        "screen_index": 0,
        "total_screens": 4
    }
}

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

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

ios-events-2.webp

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

view.setEventHandlers({
  onClose(actionId, meta) {
    console.log('Onboarding closed:', actionId);
    return true; // Allow the onboarding to close
  },
});
Пример события (нажмите, чтобы развернуть)
{
  "action_id": "close_button",
  "meta": {
    "onboarding_id": "onboarding_123",
    "screen_cid": "final_screen",
    "screen_index": 3,
    "total_screens": 4
  }
}

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

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

Самый удобный способ работы с пейволами в онбординге — сделать идентификатор действия равным идентификатору плейсмента пейвола.

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

view.setEventHandlers({
  onPaywall(actionId, meta) {
    // Dismiss onboarding before presenting paywall
    view.dismiss().then(() => {
      openPaywall(actionId);
    });
  },
});

async function openPaywall(placementId: string) {
  // Implement your paywall opening logic here
}
Пример события (нажмите, чтобы развернуть)
{
    "action_id": "premium_offer_1",
    "meta": {
        "onboarding_id": "onboarding_123",
        "screen_cid": "pricing_screen",
        "screen_index": 2,
        "total_screens": 4
    }
}

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

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

view.setEventHandlers({
  onAnalytics(event, meta) {
    console.log('Analytics event:', event.type, meta.onboardingId);
  },
});

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

ТипОписание
onboardingStartedКогда онбординг загружен
screenPresentedКогда показывается любой экран
screenCompletedКогда экран завершён. Включает необязательный elementId (идентификатор завершённого элемента) и необязательный reply (ответ пользователя). Срабатывает, когда пользователь выполняет любое действие для выхода с экрана.
secondScreenPresentedКогда показывается второй экран
userEmailCollectedСрабатывает, когда email пользователя собирается через поле ввода
onboardingCompletedСрабатывает, когда пользователь достигает экрана с ID final. Если вам нужно это событие, назначьте ID 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
    }
}