JavaScript SDK

Официальный JS SDK для Notix отправляет уведомления прямо из фронтенда. npm, CDN, TypeScript, автозахват форм, метрика посещений и отслеживание JS-ошибок.

Установка

npm

npm install @notix-hub/sdk
import { Notix } from '@notix-hub/sdk';

CDN

Скрипт инициализируется автоматически при загрузке страницы:

<script src="https://notix-hub.ru/js/notify.js"
        data-token="ntx_..."
        data-metric="true"
        data-errors="true"></script>

Привязка к домену

При создании токена укажите домен сайта (например, mysite.ru). Токен принимает запросы только с этого домена.

Возможности SDK

  • Автозахват форм — форма с data-notify автоматически отправляет уведомление при submit
  • Метрика посещенийdata-metric="true" включает авто-отправку просмотров страниц
  • Отслеживание ошибокdata-errors="true" собирает JS-ошибки батчами
  • Ручная отправкаnotix.notify({...}) из любого места кода

Формы: data-mapping

Подход: вы размечаете форму data-атрибутами. SDK при submit собирает значения полей в payload и отправляет как уведомление. Никаких шаблонов — все поля попадают в raw_payload на бекенде.

Пример: форма заявки (lead)

<form data-notify
      data-notify-type="lead"
      data-notify-tag="Сайт"
      data-notify-title="Новая заявка">

  <input name="name" placeholder="Ваше имя" required>
  <input name="phone" placeholder="Телефон">
  <textarea name="message" placeholder="Сообщение"></textarea>
  <button type="submit">Отправить</button>
</form>

Что уйдёт в вебхук:

{
  "title": "Новая заявка",
  "notification_type": "lead",
  "tag": "Сайт",
  "payload": {
    "name": "Иван",
    "phone": "+7 917 000-00-00",
    "message": "Хочу сайт"
  }
}

Пример: заказ (order) — через JS

Для заказов с корзиной используйте ручную отправку:

<button id="checkout-btn">Оформить заказ</button>

<script>
document.getElementById('checkout-btn').addEventListener('click', async () => {
  await notix.notify({
    title: 'Новый заказ',
    type: 'order',
    priority: 'high',
    tag: 'Заказы',
    payload: {
      items: [
        { name: 'Товар 1', price: 1200, qty: 2 },
        { name: 'Товар 2', price: 800, qty: 1 }
      ],
      total: 3200,
      customer: 'Иван',
      phone: '+7 917 000-00-00'
    }
  });
});
</script>

data-notify-payload — дополнительные поля

Добавьте статичный JSON в payload формы:

<form data-notify
      data-notify-type="lead"
      data-notify-tag="Лендинг"
      data-notify-title="Заявка"
      data-notify-payload='{"page": "landing-1", "utm_source": "google"}'>
  <input name="name">
  <input name="phone">
</form>

data-notify-label — читаемые имена полей

По умолчанию в payload попадают name атрибуты. Для русских названий:

<input name="phone" data-notify-label="Телефон">
<input name="email" data-notify-label="Email">

data-notify-fields — фильтр полей

Включить только указанные поля (остальные игнорируются):

<form data-notify data-notify-fields="name,phone">
  <input name="name">
  <input name="phone">
  <input name="hidden_field"> <!-- не попадёт -->
</form>

Ручная отправка: notix.notify()

const notix = new Notix({ token: 'ntx_live_xxxxxxxxxx' });

await notix.notify({
  title: 'Новый заказ',
  type: 'order',
  priority: 'high',
  tag: 'Заказы',
  payload: { amount: 12000, items: 3 }
});

// Минимально — только title
await notix.notify({ title: 'Сервер перезапущен' });

Метрика посещений

Включите data-metric="true" в script-теге — SDK собирает данные о посетителях: просмотры страниц, время на каждой, глубину прокрутки, устройство, UTM-метки. При закрытии вкладки все данные отправляются одной пачкой.

<script src="..." data-token="ntx_..." data-metric="true"></script>

Ручное включение:

const notix = new Notix({ token: '...', metricEnabled: true });

notix.trackPageView('/catalog', 'https://google.com/search?q=...');

Метрика не создаёт уведомлений в ленте. Данные агрегируются и доступны на дашборде аналитики. Push приходит раз в 10 минут со сводкой: «3 посетителя, из них 1 новый».

Device fingerprint

SDK автоматически собирает: тип устройства (desktop/mobile/tablet), браузер, ОС, разрешение экрана, язык, часовой пояс. Сервер определяет ботов (поисковые роботы, headless-браузеры) и отделяет их от реальных посетителей.

Отслеживание ошибок

Включите data-errors="true" — SDK перехватывает JS-ошибки (window.onerror, unhandledrejection) и сохраняет их в localStorage. При закрытии вкладки все накопленные ошибки отправляются одной пачкой на сервер.

<script src="..." data-token="ntx_..." data-errors="true"></script>
// Ручное включение
new Notix({
   token: '...',
   errorTrackingEnabled: true
});

Ошибки не создают уведомлений в ленте. Сервер агрегирует их, классифицирует по severity и после 10 минут затишья отправляет один push со сводкой на дашборд ошибок.

Дашборд ошибок

Включает: health score (0—100), топ-10 ошибок с трендами и стек-трейсами, разбивку по severity (critical/warning/info), почасовой график.

Health score формула: 100 - (error_rate × 200) - (critical_count × 5). Пример: 0.12 ошибок на сессию → score 78 («Хорошо»).

Конфигурация (NotixConfig)

ПараметрТипПо умолч.Описание
tokenstringAPI-токен (префикс ntx_)
endpointstringnotix-hub.ru/api/v1/webhookURL вебхука
autoCapturebooleantrueАвтозахват форм data-notify
metricEnabledbooleanfalseАвто-метрика посещений
errorTrackingEnabledbooleanfalseСбор JS-ошибок
timeoutnumber10000Таймаут запроса (мс)
debugbooleanfalseЛоги в консоль
metrikaobject{ enabled: auto }Интеграция с Яндекс.Метрикой

Метод notix.notify(payload)

ПолеТипОбяз.Описание
titlestringДаЗаголовок уведомления
bodystringНетТекст уведомления
typestringНетТип уведомления (lead, order, metric, error_batch)
tagstringНетОдиночный тег. Если нет в БД — создастся автоматически
tagsstring[] | object[]НетМассив тегов: строки или {name, color?}
prioritystringНетlow, normal, high, urgent
payloadobjectНетПроизвольный JSON (попадает в raw_payload)

Атрибуты форм

АтрибутПримерОписание
data-notifyВключает захват формы
data-notify-title"Заявка"Заголовок (по умолчанию document.title)
data-notify-type"lead"Тип уведомления (lead, order, …)
data-notify-tag"Сайт"Одиночный тег уведомления
data-notify-tags'[{"name":"tag1","color":"#F00"},"tag2"]'JSON-массив тегов (строки или объекты с name/color)
data-notify-priority"high"Приоритет
data-notify-fields"name,phone"Какие поля включить (по умолчанию все)
data-notify-payload'{...}'Дополнительный JSON, вливается в payload
data-notify-labelНа input: читаемое имя поля в payload

Атрибуты script-тега

АтрибутЗначениеОписание
data-tokenntx_...API-токен (обязательно)
data-metrictrue/falseАвто-метрика посещений
data-errorstrue/falseСбор JS-ошибок
data-debugtrue/falseЛоги в консоль
data-endpointURLСвой URL вебхука

Другие методы

МетодОписание
notix.notify(payload)Отправить уведомление
notix.capture(root?)Активировать захват форм в элементе
notix.sendPageview(url?, ref?)Отправить метрику просмотра
notix.enableErrorTracking()Включить сбор ошибок
notix.destroy()Отключить захват форм
Notix.getVisitorId()Получить/сгенерировать visitor_id

Типы уведомлений

Допустимые значения для type (предопределены в системе):

typeНазваниеИконкаЦвет
leadЗаявкаperson#F59E0B
orderЗаказreceipt_long#10B981
metricМетрикаbar_chart#8B5CF6
error_batchОшибкиwarning#EF4444

Яндекс.Метрика

SDK автоматически определяет window.ym и отправляет события:

Отключить:

new Notix({ token: '...', metrika: { enabled: false } });