npm-пакет `@livecontextapp/sdk`

Типизированный SDK для приложений со сборкой (React / Vue / Next / любой бандлер). Тот же транспорт и контракт, что и у сниппета, но с автодополнением и типами. ESM + CJS, tree-shakeable, sideEffects: false.

Важно: npm-пакет отправляет только события, атрибуты и идентификацию. Для чат-виджета всё равно нужен сниппет.

Установка

npm install @livecontextapp/sdk
# или: pnpm add @livecontextapp/sdk / yarn add @livecontextapp/sdk

Инициализация

import { createLiveContext } from '@livecontextapp/sdk';

const lc = createLiveContext({
  publicKey: 'pk_live_ВАШ_КЛЮЧ',
  apiUrl: 'https://livecontext.ru', // необязательно для same-origin
});

createLiveContext(config) возвращает изолированный инстанс (состояние в замыкании). Можно создать несколько инстансов с разными ключами.

Поле config	Тип	Обязательно	Описание
`publicKey`	string	да	Публичный ключ организации `pk_live_…`
`apiUrl`	string	нет	База API. Пусто — тот же origin.

Методы

lc.identify('user-42', { email: 'anna@shop.ru', name: 'Анна' });

lc.set('plan', 'pro');                        // string
lc.set('age', 30);                            // number
lc.set('is_vip', true);                       // boolean
lc.set('trial_ends', new Date('2026-08-15')); // Date → ISO-8601
lc.set('plan', null);                         // сброс атрибута

lc.track('purchase', { amount: 4990 });
lc.page();
lc.reset();                                   // логаут
lc.getAnonymousId();                          // текущий anonymous_id

Метод	Сигнатура	Назначение
`identify`	`(userId, traits?, userHash?)`	Связать сессию с пользователем. `userHash` — HMAC-подпись для верификации.
`track`	`(name, properties?)`	Кастомное событие.
`set`	`(variable, value)`	Атрибут контакта. `value: string \| number \| boolean \| Date \| null`.
`page`	`(properties?)`	Просмотр страницы.
`reset`	`()`	Логаут: досылает хвост, новая анонимная сессия.
`getAnonymousId`	`(): string`	Текущий `anonymous_id` (пустая строка вне браузера).

SSR (Next / Nuxt)

createLiveContext(...) безопасно вызывать на сервере: вне браузера все методы — no-op, реальная инициализация (localStorage, listeners, сеть) происходит лениво при первом вызове в браузере. Отдельные guard-проверки не нужны.

Пример: React-хук

// lib/analytics.ts
import { createLiveContext } from '@livecontextapp/sdk';
export const lc = createLiveContext({ publicKey: 'pk_live_ВАШ_КЛЮЧ' });

// компонент
useEffect(() => { lc.page(); }, [pathname]);

Транспорт

Батчинг: события уходят пакетами (POST /ingest/v1/batch), флаш по таймеру или по размеру буфера.
Надёжность: ретраи с экспоненциальным backoff, идемпотентность по messageId, досыл через sendBeacon при уходе со страницы.
Идентификатор: anonymous_id в localStorage (fallback — cookie).

Серверные события

Оплаты и другие действия с бэкенда отправляйте через Server API, а не из браузера.

npm-пакет @livecontextapp/sdk