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

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

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

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

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

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

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

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

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

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

Text("Hello, AdaptyUI!")
    .flow(
        isPresented: $flowPresented,
        flowConfiguration: flowConfiguration,
        didFinishPurchase: { product, purchaseResult in /* handle the event */ },
        didFailPurchase: { product, error in /* handle the error */ },
        didFinishRestore: { profile in /* handle the event */ },
        didFailRestore: { error in /* handle the error */ },
        didReceiveError: { error in flowPresented = false },
        didReceiveAnalyticEvent: { name, params in
            handleFlowInput(name: name, params: params)
        }
    )

func flowController(
    _ controller: AdaptyFlowController,
    didReceiveAnalyticEvent name: String,
    params: [String: any Sendable]
) {
    handleFlowInput(name: name, params: params)
}

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

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

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

func handleFlowInput(name: String, params: [String: any Sendable]) {
    guard name == "flow_user_input",
          let elementId = params["element_id"] as? String,
          let elementType = params["element_type"] as? String
    else { return }

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

    switch elementType {
    case "text_input", "email_input", "number_input", "phone_input":
        let text = params["value"] as? String
    case "date_picker", "time_picker", "date_time_picker":
        // Integer Unix time in milliseconds, not the seconds Date expects.
        let date = (params["value"] as? Int).map { Date(timeIntervalSince1970: Double($0) / 1000) }
    case "single_choice":
        let optionId = (params["item_ids"] as? [String])?.first
    case "multi_choice":
        let optionIds = params["item_ids"] as? [String]
    case "toggle":
        let isOn = params["value"] as? Bool
    default:
        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. Пользователь, просматривавший флоу на другом языке, видел другой текст.

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

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

func handleFlowInput(name: String, params: [String: any Sendable]) {
    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)
}

func handleFlowInput(name: String, params: [String: any Sendable]) {
    params["element_id"];      // "birthday"
    params["element_type"];    // "date_picker"
    params["value"];           // 645408000000   (Unix milliseconds — 1990-06-15, local midnight)
}

func handleFlowInput(name: String, params: [String: any Sendable]) {
    params["element_id"];      // "experience"
    params["element_type"];    // "single_choice"
    params["item_ids"];        // ["pro"]
    params["item_titles"];     // ["I train professionally"]
}

func handleFlowInput(name: String, params: [String: any Sendable]) {
    params["element_id"];      // "interests"
    params["element_type"];    // "multi_choice"
    params["item_ids"];        // ["sports", "music"]
    params["item_titles"];     // ["Sports", "Music"]
}

func handleFlowInput(name: String, params: [String: any Sendable]) {
    params["element_id"];      // "reminders"
    params["element_type"];    // "toggle"
    params["value"];           // true   (Bool)
}

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

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

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

Сохраняйте каждое входное значение по мере его получения обработчиком и отправляйте полный набор, когда флоу закрывается. Чтобы отловить этот момент, реализуйте flowControllerDidDisappear в вашем AdaptyFlowControllerDelegate для UIKit или передайте замыкание didDisappear модификатору .flow в SwiftUI. Оба варианта срабатывают после того, как экран флоу покидает отображение, независимо от того, завершил ли пользователь флоу или закрыл его.

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

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

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

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

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

private var flowAnswers: [String: String] = [:]

func handleFlowInput(name: String, params: [String: any Sendable]) {
    guard name == "flow_user_input",
          let elementId = params["element_id"] as? String,
          let value = params["value"] as? String
    else { return }

    flowAnswers[elementId] = value
}

func flowControllerDidDisappear(_ controller: AdaptyFlowController) {
    guard flowAnswers["email"] != nil else { return }

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

    flowAnswers.removeAll()
}

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

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

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

func handleFlowInput(name: String, params: [String: any Sendable]) {
    guard name == "flow_user_input",
          let elementId = params["element_id"] as? String,
          let value = params["value"] as? String
    else { return }

    let builder = AdaptyProfileParameters.Builder()

    switch elementId {
    case "name":
        builder.with(firstName: value)
    case "email":
        builder.with(email: value)
    default:
        return
    }

    // Delegate methods are synchronous; kick off the async update in a Task.
    Task {
        do {
            try await Adapty.updateProfile(params: builder.build())
        } catch {
            // handle the error
        }
    }
}

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

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

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

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

func handleFlowInput(name: String, params: [String: any Sendable]) {
    guard name == "flow_user_input",
          params["element_id"] as? String == "experience",
          let optionId = (params["item_ids"] as? [String])?.first
    else { return }

    let builder = AdaptyProfileParameters.Builder()
    // Set the custom attribute 'experience' to the option the user selected
    // (beginner, amateur, or pro).
    try? builder.with(customAttribute: optionId, forKey: "experience")

    Task {
        do {
            try await Adapty.updateProfile(params: builder.build())
        } catch {
            // handle the error
        }
    }
}

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