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

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

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

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

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

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

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

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

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

Введённые значения поступают в тот же колбэк, что и все остальные аналитические события флоу, под именем события flow_user_input. Переопределите onAnalyticEvent в слушателе событий флоу:

class MyFlowEventListener : AdaptyFlowDefaultEventListener() {

    override fun onAnalyticEvent(
        name: String,
        params: Map<String, Any?>,
        context: Context,
    ) {
        handleFlowInput(name, params)
    }
}

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

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

private fun handleFlowInput(name: String, params: Map<String, Any?>) {
    if (name != "flow_user_input") return

    val elementId = params["element_id"] as? String ?: return

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

    when (params["element_type"]) {
        "text_input", "email_input", "number_input", "phone_input" -> {
            val text = params["value"] as? String
        }
        "date_picker", "time_picker", "date_time_picker" -> {
            // Unix time in milliseconds. Numbers arrive as Double — read them through Number.
            val millis = (params["value"] as? Number)?.toLong()
        }
        "single_choice" -> {
            val optionId = (params["item_ids"] as? List<*>)?.firstOrNull() as? String
        }
        "multi_choice" -> {
            val optionIds = (params["item_ids"] as? List<*>)?.filterIsInstance<String>()
        }
        "toggle" -> {
            val isOn = params["value"] as? Boolean
        }
    }
}

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

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

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

• Текстовые, 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. Пользователь, просматривавший флоу на другом языке, видел другой текст.

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

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

override fun onAnalyticEvent(name: String, params: Map<String, Any?>, context: Context) {
    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)
}

override fun onAnalyticEvent(name: String, params: Map<String, Any?>, context: Context) {
    params["element_id"]       // "birthday"
    params["element_type"]     // "date_picker"
    params["value"]            // 6.45408E11   (Double — Unix milliseconds, 1990-06-15, local midnight)
}

override fun onAnalyticEvent(name: String, params: Map<String, Any?>, context: Context) {
    params["element_id"]       // "experience"
    params["element_type"]     // "single_choice"
    params["item_ids"]         // ["pro"]   (List<String>)
    params["item_titles"]      // ["I train professionally"]
}

override fun onAnalyticEvent(name: String, params: Map<String, Any?>, context: Context) {
    params["element_id"]       // "interests"
    params["element_type"]     // "multi_choice"
    params["item_ids"]         // ["sports", "music"]   (List<String>)
    params["item_titles"]      // ["Sports", "Music"]
}

override fun onAnalyticEvent(name: String, params: Map<String, Any?>, context: Context) {
    params["element_id"]       // "reminders"
    params["element_type"]     // "toggle"
    params["value"]            // true   (Boolean)
}

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

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

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

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

Примеры использования

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

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

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

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

class MyFlowEventListener : AdaptyFlowDefaultEventListener() {

    private val flowAnswers = mutableMapOf<String, String>()

    override fun onAnalyticEvent(
        name: String,
        params: Map<String, Any?>,
        context: Context,
    ) {
        if (name != "flow_user_input") return

        val elementId = params["element_id"] as? String ?: return
        val value = params["value"] as? String ?: return

        flowAnswers[elementId] = value
    }

    override fun onFlowClosed() {
        if (!flowAnswers.containsKey("email")) return

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

        flowAnswers.clear()
    }
}

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

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

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

private fun handleFlowInput(name: String, params: Map<String, Any?>) {
    if (name != "flow_user_input") return

    val elementId = params["element_id"] as? String ?: return
    val value = params["value"] as? String ?: return

    val builder = AdaptyProfileParameters.Builder()

    when (elementId) {
        "name" -> builder.withFirstName(value)
        "email" -> builder.withEmail(value)
        else -> return
    }

    Adapty.updateProfile(builder.build()) { error ->
        if (error != null) {
            // handle the error
        }
    }
}

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

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

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

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

private fun handleFlowInput(name: String, params: Map<String, Any?>) {
    if (name != "flow_user_input") return
    if (params["element_id"] != "experience") return

    val optionId = (params["item_ids"] as? List<*>)?.firstOrNull() as? String ?: return

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

    Adapty.updateProfile(builder.build()) { error ->
        if (error != null) {
            // handle the error
        }
    }
}

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