JavaScript SDK
Официальный JS SDK для Notix отправляет уведомления прямо из фронтенда. npm, CDN, TypeScript, автозахват форм, метрика посещений и отслеживание JS-ошибок.
Установка
npm
npm install @notix-hub/sdkimport { 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)
| Параметр | Тип | По умолч. | Описание |
|---|---|---|---|
token | string | — | API-токен (префикс ntx_) |
endpoint | string | notix-hub.ru/api/v1/webhook | URL вебхука |
autoCapture | boolean | true | Автозахват форм data-notify |
metricEnabled | boolean | false | Авто-метрика посещений |
errorTrackingEnabled | boolean | false | Сбор JS-ошибок |
timeout | number | 10000 | Таймаут запроса (мс) |
debug | boolean | false | Логи в консоль |
metrika | object | { enabled: auto } | Интеграция с Яндекс.Метрикой |
Метод notix.notify(payload)
| Поле | Тип | Обяз. | Описание |
|---|---|---|---|
title | string | Да | Заголовок уведомления |
body | string | Нет | Текст уведомления |
type | string | Нет | Тип уведомления (lead, order, metric, error_batch) |
tag | string | Нет | Одиночный тег. Если нет в БД — создастся автоматически |
tags | string[] | object[] | Нет | Массив тегов: строки или {name, color?} |
priority | string | Нет | low, normal, high, urgent |
payload | object | Нет | Произвольный 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-token | ntx_... | API-токен (обязательно) |
data-metric | true/false | Авто-метрика посещений |
data-errors | true/false | Сбор JS-ошибок |
data-debug | true/false | Логи в консоль |
data-endpoint | URL | Свой 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 и отправляет события:
notix_sent— уведомление отправленоnotix_error— ошибка отправкиnotix_form_captured— захвачена форма
Отключить:
new Notix({ token: '...', metrika: { enabled: false } });