JavaScript API: пользователи, email и события

Чтобы видеть в «Аудитории» имя и email посетителя, передайте их из своего приложения через JavaScript API. Так вы сможете найти человека в списке и посмотреть историю его действий.

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

Настройте сбор данных

В боковом меню откройте «Интеграция виджета»:

1. Создайте публичный ключ, если его ещё нет.
2. В разделе «Сбор аудитории и событий» включите «Собирать данные о посетителях».
3. В поле «Разрешённые адреса сайтов» укажите адрес сайта, например https://app.example.com, без пути страницы и завершающего /.
4. В поле «Когда собирать данные» выберите режим и нажмите «Сохранить настройки».

В режиме «Только после согласия» сайт должен получить согласие пользователя до передачи его данных. Порядок вызовов приведён ниже, в разделе «Согласие на сбор данных».

Подключите виджет

Если виджет уже есть на сайте, второй раз подключать его не нужно.

Для обычного HTML-сайта добавьте скрипт виджета и файл с вашим кодом:

<script
  defer
  src="https://app.flowtomate.ru/widget/v1/widget.js"
  data-flowtomate-key="pub_live_REPLACE_WITH_YOUR_KEY"
  data-flowtomate-api="https://api.flowtomate.ru">
</script>
<script defer src="/flowtomate-integration.js"></script>

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

Файл /flowtomate-integration.js создаёт ваш разработчик. В нём он размещает вызовы из этой инструкции. Атрибут defer сохраняет порядок: сначала браузер выполнит скрипт виджета, затем ваш код.

Для GTM и React есть отдельная инструкция по установке. При подключении через async, GTM или React дождитесь загрузки скрипта перед обращением к window.FlowtomateWidget. После появления объекта выполните await window.FlowtomateWidget.ready(), затем переходите к остальным вызовам.

Примеры с await запускайте внутри async-функции или в консоли браузера на тестовом сайте. На сервере этот код не работает.

Согласие на сбор данных

В режиме «Только после согласия» свяжите вызовы API с баннером согласия на вашем сайте. После загрузки виджета и согласия пользователя выполните:

window.FlowtomateWidget.setConsent('granted');

await window.FlowtomateWidget.identify('user_42', {
  email: 'anna@example.com',
  name: 'Анна'
});

Здесь и далее используем вымышленные данные. В своём коде подставляйте данные текущего пользователя.

Вызывайте setConsent('granted') после согласия в баннере. Сам по себе вход в аккаунт такого согласия не даёт. До согласия не вызывайте identify, setTraits и track.

В режиме «Без запроса согласия» отдельный вызов setConsent('granted') не нужен. Если пользователь уже отказался от сбора, отказ продолжает действовать.

При отказе или отзыве согласия вызовите:

window.FlowtomateWidget.setConsent('denied');

Виджет прекратит сбор и очистит очередь событий. В своём коде тоже прекратите вызовы identify и setTraits: если передать в них данные после отказа, они могут попасть в запросы за настройками виджета.

Значение unknown убирает сохранённый выбор. В режиме «Без запроса согласия» после него сбор может продолжиться, поэтому для отказа используйте denied.

setConsent ничего не возвращает. Добавление await не позволит дождаться применения настроек. Подробнее об этом — в руководстве по согласию.

Передайте ID и email пользователя

После входа пользователя вызовите identify:

await window.FlowtomateWidget.ready();

await window.FlowtomateWidget.identify('user_42', {
  email: 'anna@example.com',
  name: 'Анна',
  plan: 'pro',
  role: 'admin',
  company_id: 'company_17'
});

Первый аргумент, user_42, — ID пользователя в вашей системе. Передавайте один и тот же ID при повторном входе и на другом устройстве. Если ID у вас хранится числом, преобразуйте его в строку: String(user.id).

Остальные поля описывают пользователя:

Поле	Что передать
email	Email, по которому вы сможете найти профиль.
name	Имя, которое вы увидите в профиле.
plan	Тариф, например pro.
role	Роль в вашем продукте, например admin.
company_id	ID компании. Он сохранится как поле пользователя; отдельной карточки компании не будет.

Можно добавить свои поля. Все значения передавайте строками: seats: '12', onboarding_done: 'true'. В названиях полей используйте латинские буквы, цифры, _, - и .. Префикс flowtomate. занят служебными полями. Вложенные объекты API не принимает.

Email храните отдельным полем: он может измениться, а ID должен остаться прежним. По совпадению email Flowtomate не объединяет профили с разными ID. Пароли, токены и данные банковских карт не передавайте.

После успешной записи вы найдёте пользователя в «Аудитории» со статусом «Известный». В его профиле будет и та активность, которую виджет успел собрать в этом браузере до входа.

Вызывайте identify после входа и при перезагрузке страницы, когда ваше приложение получило данные текущего пользователя. Если приложение меняет страницы без перезагрузки, повторять вызов при каждом переходе не нужно.

Обновите email, тариф или другие поля

Для изменения данных используйте setTraits:

await window.FlowtomateWidget.setTraits({
  email: 'anna.new@example.com',
  plan: 'team'
});

Сначала вызовите identify, чтобы связать посетителя с ID. Затем через setTraits передавайте только изменившиеся поля. Остальные значения останутся прежними. Виджет также обновит контент с учётом новых данных.

Если не передать поле, оно не удалится. Отдельного метода для удаления поля в этом API нет.

Запишите действие пользователя

Вызовите track после нужного действия. Например, после успешного создания отчёта:

window.FlowtomateWidget.track('report_created', {
  report_type: 'sales',
  rows: 120,
  shared: false
});

В этом примере report_created — название события, а остальные поля — данные об отчёте. Здесь можно передавать строки, числа, true, false, null и массивы строк или чисел. Email и имя передавайте через identify или setTraits.

Для названия события используйте маленькие латинские буквы, цифры и _. Начинайте с буквы и укладывайтесь в 100 знаков. Префиксы flowtomate_, popup_, checklist_, tour_, page_, session_, survey_, feedback_ и hint_ заняты служебными событиями. Другие ограничения есть в документации событий.

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

При выходе из аккаунта вызовите reset

При выходе пользователя выполните:

await window.FlowtomateWidget.reset();

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

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

await window.FlowtomateWidget.reset();
await window.FlowtomateWidget.identify('user_73', {
  email: 'pavel@example.com',
  name: 'Павел'
});

Если согласие нужно запросить заново, используйте await window.FlowtomateWidget.reset({ clearConsent: true }). В режиме «Только после согласия» дождитесь нового согласия перед вызовом identify.

Для выхода используйте reset(). Метод destroy() убирает виджет со страницы и не очищает сохранённые данные пользователя.

Проверьте, что данные дошли

Проверяйте интеграцию на тестовом проекте или с тестовым пользователем:

1. Откройте сайт, указанный в настройках проекта, и дождитесь загрузки виджета. Если нужно, дайте согласие через баннер.
2. Вызовите identify с тестовым ID и email. В кабинете откройте «Аудитория» и найдите профиль. Проверьте статус «Известный», а на вкладке «Обзор» — переданные поля.
3. Измените plan через setTraits. Перезагрузите страницу кабинета и проверьте новый тариф.
4. Вызовите track('report_created', { report_type: 'sales' }). После отправки найдите событие на вкладке «События» профиля.
5. Перезагрузите сайт и войдите под тем же пользователем. Он должен остаться в прежнем профиле. Затем выйдите и войдите другим тестовым аккаунтом: новые действия должны появляться у него.

Вызов ready() сам по себе не подтверждает, что настройки загрузились и данные сохранились. Результат проверяйте в кабинете.

Если что-то не работает

Ошибки вызовов с await обрабатывайте через try/catch. Например, после загрузки скрипта и получения нужного согласия:

try {
  const widget = window.FlowtomateWidget;
  if (!widget) throw new Error('Скрипт Flowtomate не загрузился');

  await widget.ready();
  await widget.identify('user_42', { email: 'anna@example.com' });
} catch {
  console.warn('Не удалось передать пользователя в Flowtomate');
}

Проблема	Что проверить
Нет window.FlowtomateWidget	Дождитесь загрузки widget.js. Проверьте порядок скриптов и ошибки CSP в консоли.
Пользователь остался анонимным	Проверьте вызов identify: ID должен быть непустой строкой. Убедитесь, что включили сбор, разрешили адрес сайта и получили нужное согласие.
Не находится email	Проверьте поле email в identify или setTraits, выбранный проект и сетевые ошибки.
У одного человека несколько профилей	Сравните ID, которые передаёте при разных входах и на разных устройствах.
Действия попадают прежнему пользователю	Вызывайте reset() при выходе и дожидайтесь его перед новым identify.
Нет события	Проверьте согласие, название и поля события, а также ошибки сети.
Изменили настройки, но данные не идут	Сохраните настройки и перезагрузите страницу сайта.

Дополнительные проверки есть в инструкции по диагностике. Если обращаетесь за помощью, не публикуйте данные реальных пользователей и токены.

Открытие поп-апов, туров и других материалов

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

Задача	Вызов	Результат
Открыть поп-ап	await window.FlowtomateWidget.openPopup('POPUP_ID')	true, если открылся; иначе false. В настройках поп-апа включите ручной запуск.
Запустить тур	await window.FlowtomateWidget.startTour('TOUR_ID')	Статус started, pending, ineligible или not_found в объекте ответа.
Открыть чеклист	window.FlowtomateWidget.openChecklist('CHECKLIST_ID')	Ничего не возвращает.
Открыть обратную связь	window.FlowtomateWidget.openFeedback('FEEDBACK_ID')	Ничего не возвращает.
Обновить настройки и контент	await window.FlowtomateWidget.refresh()	Дождитесь обновления через await; ошибку обработайте в catch.
Узнать версию	window.FlowtomateWidget.version	Номер версии в виде строки.

Материал должен быть опубликован и загружен в виджет. Для ручного поп-апа включите ручной запуск; для тура действуют правила показа. Перед открытием чеклиста и обратной связи дождитесь ready(). Примеры и причины отказов есть в руководстве по ручному запуску.

Полный список методов и очередь вызовов до загрузки виджета описаны в справочнике JavaScript API. Отдельного публичного REST API для передачи аудитории и событий с вашего сервера сейчас нет.