Обработка данных из флоу в Flutter SDK

Когда пользователь вводит текст в поле ввода, отвечает на вопрос викторины или переключает тумблер во флоу, SDK передаёт это значение в ваше приложение через колбэк аналитики.

Чаще всего приложения используют эти данные для:

• Регистрация пользователей на собственном бэкенде: Возьмите email и имя, которые пользователь ввёл в онбординге, и создайте его аккаунт, когда флоу закроется.
• Сохранение ответов и предпочтений: Отслеживайте, что выбрал пользователь, чтобы приложение могло использовать это позже — например, записать в его профиль Adapty в виде custom attributes.
• Кастомизация будущих флоу: Сохраните ответы на вопросы как custom attributes, затем настройте таргетинг на плейсмент позже — чтобы каждый сегмент видел свой флоу или свой пейвол внутри него.
• Передача данных в сторонние аналитические платформы: Пересылайте ответы в Amplitude, Mixpanel или любой другой инструмент продуктовой аналитики, который вы используете.

Поля ввода и группы выбора автоматически передают свои значения. Чтобы различать их в коде, задайте каждому полю ввода уникальный Element ID, а каждой группе выбора — Group ID в конструкторе.

Перед началом работы

Вам понадобится:

• Adapty SDK v4 или новее: колбэки флоу отсутствуют в более ранних версиях.
• Флоу, собранный в Flow & Paywall Builder: только флоу передают входные значения через этот колбэк.
• Недавно опубликованная версия флоу: флоу передаёт входные значения только если вы опубликовали его после того, как эта функция стала доступна. Если ничего не приходит в приложение, опубликуйте новую версию флоу и попробуйте снова.

Получение введённых значений

Введённые значения передаются в тот же колбэк, что и все остальные аналитические события флоу, под именем события flow_user_input. Реализуйте flowViewDidReceiveAnalyticEvent в наблюдателе, который вы регистрируете через AdaptyUI().setFlowsEventsObserver:

void flowViewDidReceiveAnalyticEvent(
  AdaptyUIFlowView view,
  String name,
  Map<String, dynamic> params,
) {
  handleFlowInput(name, params);
}

Колбэк flowViewDidReceiveAnalyticEvent передаёт все аналитические события флоу, включая просмотры экранов.

• Параметр name содержит название события. Чтобы отфильтровать события пользовательского ввода, сравните name со значением flow_user_input.
• Параметр element_type указывает категорию элемента.
• Значение ввода хранится в разных параметрах в зависимости от типа элемента:
  • Текстовые поля, выборщики и переключатели хранят пользовательский ввод в value
  • Группы с возможностью выбора передают активные варианты в item_ids и item_titles

void handleFlowInput(String name, Map<String, dynamic> params) {
  if (name != 'flow_user_input') return;

  final elementId = params['element_id'] as String;

  // The screen the input sits on. Pair it with elementId to tell apart
  // two fields that share an Element ID on different screens.
  final screenId = params['instanceId'] as String?;

  switch (params['element_type'] as String) {
    case 'text_input':
    case 'email_input':
    case 'number_input':
    case 'phone_input':
      final text = params['value'] as String;
      break;
    case 'date_picker':
    case 'time_picker':
    case 'date_time_picker':
      // Unix time in milliseconds. Arrives as int on iOS and double on Android — read it through num.
      final date = DateTime.fromMillisecondsSinceEpoch((params['value'] as num).toInt());
      break;
    case 'single_choice':
      final optionId = (params['item_ids'] as List).cast<String>().first;
      break;
    case 'multi_choice':
      final optionIds = (params['item_ids'] as List).cast<String>();
      break;
    case 'toggle':
      final isOn = params['value'] as bool;
      break;
  }
}

Чтобы убедиться, что коллбэк срабатывает, взаимодействуйте с полем ввода в тестовой сборке вашего приложения. Если обработчик коллбэка не получает событие, проверьте предварительные требования. Убедитесь, что флоу был опубликован после того, как эта функция стала доступной.

Когда приложение получает входные данные

Следующие элементы вызывают это событие:

• Текстовые, email-, числовые и телефонные поля
• Выборщики даты, времени и даты со временем
• Группы с единственным и множественным выбором, а также переключатели

Следующие не вызывают:

• Поля пароля, выборы продукта и переключения вкладок
• Поля ввода внутри элемента Header, который является общим для всех экранов
• Группы с выбором, у которых есть дублирующиеся или отсутствующие Element ID у опций, либо Group ID, повторно используемый на другом экране. Такая группа не отправляет ничего, а не часть ответа.

Событие срабатывает когда:

• Поле теряет фокус. Очищенное поле сообщает пустую строку; поле, которое пользователь ни разу не редактировал, не сообщает ничего. Плейсхолдер не является значением. Если пользователь возвращается к полю, редактирует его и снова уходит, следует второе событие.
• Пользователь закрывает выборщик после выбора нового значения. Закрытие без изменений не сообщает ничего.
• Пользователь нажимает на опцию или переключатель. Событие множественного выбора содержит список всех выбранных опций, поэтому снятие последней выбранной опции отправляет два пустых массива.

Событие не срабатывает когда:

• Пользователь набирает текст. Потока нажатий клавиш нет — только значение, которое поле содержит в момент потери фокуса.
• Пользователь отправляет или закрывает флоу. Значение, которое в этот момент ещё редактируется, может быть потеряно; в разделе ограничения доставки описано, как спроектировать последний экран с учётом этого.
• Значение устанавливается без взаимодействия с пользователем. Опция, отмеченная Set as default, предвыбирается при открытии экрана, а действие Set Variable может выбрать опцию или заполнить поле ввода из другого взаимодействия. Ни то ни другое не отправляет событие; предзаполненное поле ввода сообщается только после того, как пользователь его отредактирует.

Что вы получаете

Коллбэк доставляет два типа событий. Фильтруйте по name, чтобы отображать только события flow_user_input. JSON-ответ выглядит так:

{
  "name": "flow_user_input",
  "instanceId": "scr_registration",
  "isBackendEvent": false,
  "isCustomerEvent": true,
  "element_id": "email",
  "element_type": "email_input",
  "value": "jane@example.com"
}

Что передаёт каждый элемент:

Для ветвления по ответу сравнивайте item_ids, а не item_titles. Заголовок — производная величина: Element Title варианта, если он задан; иначе его текст в вашей локали по умолчанию; иначе его Element ID. Пользователь, просматривавший флоу на другом языке, видел другой текст.

Примеры событий

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

void flowViewDidReceiveAnalyticEvent(
  AdaptyUIFlowView view,
  String name,
  Map<String, dynamic> params,
) {
  name;                      // 'flow_user_input'
  params['name'];            // 'flow_user_input'
  params['instanceId'];      // 'scr_J260KU5q'
  params['isCustomerEvent']; // true
  params['isBackendEvent'];  // false
  params['element_id'];      // 'email'
  params['element_type'];    // 'email_input'
  params['value'];           // 'jane@example.com'   (String)
}

void flowViewDidReceiveAnalyticEvent(
  AdaptyUIFlowView view,
  String name,
  Map<String, dynamic> params,
) {
  params['element_id'];      // 'birthday'
  params['element_type'];    // 'date_picker'
  params['value'];           // 645408000000   (Unix milliseconds — 1990-06-15, local midnight; int on iOS, double on Android)
}

void flowViewDidReceiveAnalyticEvent(
  AdaptyUIFlowView view,
  String name,
  Map<String, dynamic> params,
) {
  params['element_id'];      // 'experience'
  params['element_type'];    // 'single_choice'
  params['item_ids'];        // ['pro']   (List)
  params['item_titles'];     // ['I train professionally']
}

void flowViewDidReceiveAnalyticEvent(
  AdaptyUIFlowView view,
  String name,
  Map<String, dynamic> params,
) {
  params['element_id'];      // 'interests'
  params['element_type'];    // 'multi_choice'
  params['item_ids'];        // ['sports', 'music']   (List)
  params['item_titles'];     // ['Sports', 'Music']
}

void flowViewDidReceiveAnalyticEvent(
  AdaptyUIFlowView view,
  String name,
  Map<String, dynamic> params,
) {
  params['element_id'];      // 'reminders'
  params['element_type'];    // 'toggle'
  params['value'];           // true   (bool)
}

Доставка и ограничения

• Побеждает последнее значение: вы получаете одно событие на поле с тем значением, на котором пользователь остановился, а не поток каждого нажатия клавиши. Если он редактирует поле, до вас дойдёт только последняя версия.
• Нет гарантии отправки: значения поступают к вам по мере того, как пользователь движется по флоу, и он может выйти в любой момент. Дождитесь закрытия флоу, прежде чем считать набор ответов завершённым.
• Доставка по возможности: если пользователь закрывает флоу или сворачивает приложение, пока поле ещё в фокусе или пикер открыт, это значение может быть потеряно.

Чтобы значение последнего поля было надёжным, завершайте флоу экраном без полей ввода и пикеров, и закрывайте флоу явным действием пользователя, а не автоматически при появлении этого экрана. Переход на финальный экран снимает фокус с предыдущего поля — именно это и отправляет его значение.

Сохраняйте каждое входное значение по мере их получения наблюдателем и отправляйте полный набор при закрытии флоу. Чтобы отловить этот момент, реализуйте flowViewDidDisappear на том же наблюдателе. Метод вызывается при закрытии экрана флоу — независимо от того, завершил ли пользователь флоу или закрыл его на полпути.

Варианты использования

Регистрация пользователей на вашем бэкенде

Собирайте значения по мере их поступления и отправляйте их одним запросом после закрытия флоу, чтобы передать полный набор ответов.

Экран закрывается как при завершении флоу, так и при его прерывании на полпути. Перед обращением к бэкенду проверяйте наличие нужных полей.

Флоу не может отображать ошибки бэкенда. Коллбэк не возвращает никакого значения, и в SDK нет метода для передачи данных в активный флоу. Если регистрация завершится с ошибкой — например, потому что email уже используется, — покажите её в собственном интерфейсе после закрытия флоу.

final Map<String, String> flowAnswers = {};

void flowViewDidReceiveAnalyticEvent(
  AdaptyUIFlowView view,
  String name,
  Map<String, dynamic> params,
) {
  if (name != 'flow_user_input') return;

  final elementId = params['element_id'];
  final value = params['value'];
  if (elementId is! String || value is! String) return;

  flowAnswers[elementId] = value;
}

void flowViewDidDisappear(AdaptyUIFlowView view) {
  if (!flowAnswers.containsKey('email')) return;

  // Send flowAnswers to your backend here to create the account.

  flowAnswers.clear();
}

Обогащайте профили пользователей данными

Чтобы связать введённые пользователем данные с его профилем и не спрашивать одно и то же дважды, обновляйте профиль пользователя по мере поступления значений.

Например, если в вашем флоу есть текстовое поле с Element ID name и поле для email с Element ID email:

void handleFlowInput(String name, Map<String, dynamic> params) async {
  if (name != 'flow_user_input') return;

  final value = params['value'];
  if (value is! String) return;

  final builder = AdaptyProfileParametersBuilder();

  switch (params['element_id'] as String) {
    case 'name':
      builder.setFirstName(value);
      break;
    case 'email':
      builder.setEmail(value);
      break;
    default:
      return;
  }

  try {
    await Adapty().updateProfile(builder.build());
  } on AdaptyError catch (adaptyError) {
    // handle the error
  }
}

Настройте флоу, которые показываются позже

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

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

1. Добавьте квиз в ваш флоу. Присвойте выбираемой группе Group ID experience, а каждому варианту — осмысленный Element ID.
2. Обработайте ответы и задайте пользовательские атрибуты для пользователя.

void handleFlowInput(String name, Map<String, dynamic> params) async {
  if (name != 'flow_user_input') return;
  if (params['element_id'] != 'experience') return;

  final optionId = (params['item_ids'] as List).cast<String>().first;

  final builder = AdaptyProfileParametersBuilder();
  // Set the custom attribute 'experience' to the option the user selected
  // (beginner, amateur, or pro).
  builder.setCustomStringAttribute(optionId, 'experience');

  try {
    await Adapty().updateProfile(builder.build());
  } on AdaptyError catch (adaptyError) {
    // handle the error
  }
}

3. Создайте сегмент для каждого значения пользовательского атрибута.
4. Создайте плейсмент и добавьте аудиторию для каждого сегмента.
5. Отобразите флоу для этого плейсмента в вашем приложении.