Передача атрибутов пользователя через JS SDK

По умолчанию Нотифлоу распознает посетителей анонимно — через fingerprint браузера (UUID в cookie notiflow_visitor_id). Это работает для анонимов, но у них нет истории при смене устройства и нельзя таргетировать виджеты по пользовательским атрибутам (тариф, роль, дата регистрации). Идентификация через SDK связывает фингерпринт с реальным ID вашего пользователя и передает произвольные атрибуты.

Когда вызывать

Сразу после авторизации пользователя на вашем сайте. Обычно это страница после логина: /dashboard, /account, любой внутренний маршрут SPA. До логина вы не знаете, кто посетитель — идентифицировать нечего.

Глобальная функция SDK — _nf

Embed-сниппет Нотифлоу публикует на странице функцию с именем _nf. Это единая точка входа для всех SDK-методов: init, identify, group, event, reset.

<script>
    (function (w, d, s, o, f, js, fjs) {
        w[o] = w[o] || function () { w[o].q = w[o].q || []; w[o].q.push(arguments); };
        js = d.createElement(s); fjs = d.getElementsByTagName(s)[0];
        js.id = o; js.src = f; js.async = 1;
        fjs.parentNode.insertBefore(js, fjs);
    }(window, document, 'script', '_nf', 'https://cp.notiflow.ru/js/widget.js'));
    _nf('init', { api_key: 'YOUR_API_KEY' });
</script>

Вызовы до загрузки бандла складываются в очередь и выполняются после инициализации — дополнительных проверок на готовность не нужно.

Identify — один объект-аргумент

Все поля передаются одним объектом. Обязательное поле — user_id, остальные опциональны.

_nf('identify', {
  user_id: 'user_12345',             // ваш внутренний ID
  email: 'ivanov@site.ru',
  name: 'Иван Иванов',
  phone: '+7 (495) 000-00-00',
  plan: 'pro',                        // произвольные атрибуты
  signed_up_at: '2026-01-15',
  company: 'ООО Ромашка'
});

Стандартные поля (user_id, email, name, phone) мапятся в колонки таблицы контактов. Остальные ключи уходят в custom_properties и доступны для таргетинга сегментов и условий показа виджетов.

Что происходит после вызова

SDK отправляет POST /api/widgets/identify с телом { fingerprint, user_id, traits } и заголовком X-Api-Key. Бэкенд находит или создает контакт по external_id = user_id, связывает текущий fingerprint с этим контактом, мержит анонимный профиль в именованный (лог событий, теги, устройства — все переезжает на целевой контакт). Последующие действия этого пользователя из любого браузера, где он залогинен, попадают в один профиль.

Обновление атрибутов

Повторный вызов _nf('identify', { ... }) с тем же user_id и новыми значениями обновляет поля контакта. Удобно вызывать на ключевых событиях продукта — смена тарифа, активация фичи, подтверждение почты.

Group — привязка к компании (B2B)

_nf('group', {
  company_id: 'company_42',
  name: 'ООО Ромашка',
  domain: 'site.ru',
  plan: 'enterprise',
  employees: 250
});

Связывает текущий контакт с компанией. Поля компании доступны для фильтров сегментов (например, «клиенты с company.plan = enterprise»).

Event — кастомные события продукта

_nf('event', 'purchase', {
  order_id: '10042',
  amount: 4990,
  currency: 'RUB'
});

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

Reset — при логауте

_nf('reset');

Отсылает POST /api/widgets/reset, затем очищает cookie notiflow_visitor_id, sessionStorage и localStorage Нотифлоу. Следующий посетитель с того же браузера получит новый анонимный фингерпринт и не будет связан с предыдущим пользователем.

Идентификация с бэкенда (server-side)

Если фронтенд не знает всех атрибутов (например, тариф хранится только в бэкенде) или нужна гарантия доставки без зависимости от клиентского JS, используйте Server REST API: POST /api/v1/contacts.

curl -X POST https://cp.notiflow.ru/api/v1/contacts \
  -H "X-Api-Key: {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "user_12345",
    "email": "ivanov@site.ru",
    "name": "Иван Иванов",
    "custom_properties": { "plan": "pro", "mrr": 4990 }
  }'

Авторизация через заголовок X-Api-Key (ключ создается в кабинете: Настройки → API-ключи). Подробная схема запросов и Try It — в интерактивной документации на /docs/api.

Проверка

После вызова identify в DevTools вкладка Network → запрос /api/widgets/identify должен вернуть 200. В ответе есть contact_id — если 200 и id пришел, контакт создан.

В кабинете: Контакты — новая запись появится мгновенно. Если вы передали plan или другие атрибуты, они видны на карточке в блоке «Custom properties».

Частые ошибки

• _nf is not defined — бандл не успел загрузиться или сниппет не вставлен на страницу. Проверьте, что cp.notiflow.ru/js/widget.js есть в Network.
• 403 Invalid API key — в init передан чужой или устаревший ключ. Проверьте Настройки → API-ключи.
• Контакт не обновляется при повторном identify — user_id отличается от первого вызова. Бэкенд ищет по external_id — должен быть одним и тем же.
• Атрибуты не видны в сегментах — стандартные поля (email, name, phone) доступны напрямую; остальные лежат в custom_properties.* — в фильтре сегмента выбирайте именно этот путь.