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

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

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

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

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

Прежде чем начать

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

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

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

Входные значения поступают в тот же колбэк, что и все остальные аналитические события флоу, под именем события flow_user_input. Реализуйте FlowViewDidReceiveAnalyticEvent в слушателе, который вы регистрируете через Adapty.SetFlowsEventsListener:

public void FlowViewDidReceiveAnalyticEvent(
    AdaptyUIFlowView view,
    string name,
    IReadOnlyDictionary<string, object> parameters
) {
    HandleFlowInput(name, parameters);
}

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

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

private void HandleFlowInput(string name, IReadOnlyDictionary<string, object> parameters) {
    if (name != "flow_user_input") return;

    var elementId = parameters["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.
    var screenId = parameters["instanceId"] as string;

    switch (parameters["element_type"] as string) {
        case "text_input":
        case "email_input":
        case "number_input":
        case "phone_input":
            var text = parameters["value"] as string;
            break;
        case "date_picker":
        case "time_picker":
        case "date_time_picker":
            // Unix time in milliseconds.
            var millis = Convert.ToInt64(parameters["value"]);
            break;
        case "single_choice":
            var optionId = (parameters["item_ids"] as JArray)?.First?.ToString();
            break;
        case "multi_choice":
            var optionIds = (parameters["item_ids"] as JArray)?.ToObject<List<string>>();
            break;
        case "toggle":
            var isOn = (bool)parameters["value"];
            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. Пользователь, просматривавший флоу на другом языке, видел другой текст.

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

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

public void FlowViewDidReceiveAnalyticEvent(
    AdaptyUIFlowView view,
    string name,
    IReadOnlyDictionary<string, object> parameters
) {
    var eventName       = name;                          // "flow_user_input"
    var paramName       = parameters["name"];            // "flow_user_input"
    var screenId        = parameters["instanceId"];      // "scr_J260KU5q"
    var isCustomerEvent = parameters["isCustomerEvent"]; // true
    var isBackendEvent  = parameters["isBackendEvent"];  // false
    var elementId       = parameters["element_id"];      // "email"
    var elementType     = parameters["element_type"];    // "email_input"
    var value           = parameters["value"];           // "jane@example.com"   (string)
}

public void FlowViewDidReceiveAnalyticEvent(
    AdaptyUIFlowView view,
    string name,
    IReadOnlyDictionary<string, object> parameters
) {
    var elementId   = parameters["element_id"];   // "birthday"
    var elementType = parameters["element_type"]; // "date_picker"
    var value       = parameters["value"];        // 645408000000   (long — Unix milliseconds, 1990-06-15, local midnight)
}

public void FlowViewDidReceiveAnalyticEvent(
    AdaptyUIFlowView view,
    string name,
    IReadOnlyDictionary<string, object> parameters
) {
    var elementId   = parameters["element_id"];   // "experience"
    var elementType = parameters["element_type"]; // "single_choice"
    var itemIds     = parameters["item_ids"];     // ["pro"]   (JArray)
    var itemTitles  = parameters["item_titles"];  // ["I train professionally"]
}

public void FlowViewDidReceiveAnalyticEvent(
    AdaptyUIFlowView view,
    string name,
    IReadOnlyDictionary<string, object> parameters
) {
    var elementId   = parameters["element_id"];   // "interests"
    var elementType = parameters["element_type"]; // "multi_choice"
    var itemIds     = parameters["item_ids"];     // ["sports", "music"]   (JArray)
    var itemTitles  = parameters["item_titles"];  // ["Sports", "Music"]
}

public void FlowViewDidReceiveAnalyticEvent(
    AdaptyUIFlowView view,
    string name,
    IReadOnlyDictionary<string, object> parameters
) {
    var elementId   = parameters["element_id"];   // "reminders"
    var elementType = parameters["element_type"]; // "toggle"
    var value       = parameters["value"];        // true   (bool)
}

Передача данных и ограничения

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

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

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

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

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

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

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

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

private readonly Dictionary<string, string> flowAnswers = new Dictionary<string, string>();

public void FlowViewDidReceiveAnalyticEvent(
    AdaptyUIFlowView view,
    string name,
    IReadOnlyDictionary<string, object> parameters
) {
    if (name != "flow_user_input") return;
    if (!parameters.TryGetValue("value", out var raw) || !(raw is string value)) return;

    var elementId = parameters["element_id"] as string;
    flowAnswers[elementId] = value;
}

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

private void HandleFlowInput(string name, IReadOnlyDictionary<string, object> parameters) {
    if (name != "flow_user_input") return;
    if (!parameters.TryGetValue("value", out var raw) || !(raw is string value)) return;

    var builder = new AdaptyProfileParameters.Builder();

    switch (parameters["element_id"] as string) {
        case "name":
            builder = builder.SetFirstName(value);
            break;
        case "email":
            builder = builder.SetEmail(value);
            break;
        default:
            return;
    }

    Adapty.UpdateProfile(builder.Build(), (error) => {
        if (error != null) {
            // handle the error
        }
    });
}

Настройка флоу, отображаемых позже

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

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

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

private void HandleFlowInput(string name, IReadOnlyDictionary<string, object> parameters) {
    if (name != "flow_user_input") return;
    if ((parameters["element_id"] as string) != "experience") return;

    var optionId = (parameters["item_ids"] as JArray)?.First?.ToString();
    if (optionId == null) return;

    var builder = new AdaptyProfileParameters.Builder();
    // Set the custom attribute 'experience' to the option the user selected
    // (beginner, amateur, or pro).
    builder = builder.SetCustomStringAttribute("experience", optionId);

    Adapty.UpdateProfile(builder.Build(), (error) => {
        if (error != null) {
            // handle the error
        }
    });
}

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