Browser SDK для приложений со сборкой

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

Что даст пакет по сравнению со скриптом

• Типы TypeScript для событий, свойств и параметров инициализации.
• Явный контроль момента инициализации вместо автозапуска по тегу.
• Дополнительные модули приходят из вашего бандла, а не подгружаются с внешнего адреса — удобно при строгой политике безопасности.
• Точка входа не имеет побочных эффектов, поэтому её безопасно импортировать в коде, который выполняется и на сервере.

Модель работы

import { createClient } from '@actionpulse/browser';

const analytics = createClient();

analytics.init({
  token: 'YOUR_BROWSER_TOKEN',
  apiHost: 'https://YOUR_ACTIONPULSE_HOST',
  consent: 'required',
});

createClient() создаёт клиент, init() его настраивает. Пока согласие не получено, клиент полностью пассивен.

Дальше доступны:

analytics.setConsent('granted');

analytics.track('signup_completed', { plan: 'pro' });
analytics.identify('YOUR_USER_ID', { plan: 'pro' });

analytics.getConsent();
analytics.getSessionId();  // пока сбор не разрешён — undefined

await analytics.flush();   // дослать накопленное
analytics.clearQueue();    // выбросить неотправленное
analytics.reset();         // забыть текущего пользователя

У track() есть третий аргумент для случаев, когда событие нужно привязать к конкретному моменту или сделать повторную отправку безопасной:

analytics.track('checkout_started', { plan: 'pro' }, {
  eventId: '8b0d3f2e-1c4a-4f0e-9b1d-2a3c4d5e6f70',
  time: '2026-07-27T12:00:00Z',
  schemaVersion: 1,
});

SSR и граница браузера

Корневой импорт не имеет побочных эффектов, поэтому модуль можно импортировать в универсальном коде. А вот init() требует браузерных глобальных объектов и при вызове на сервере бросает понятную ошибку — вызывайте его только на клиенте.

Практическое правило: создавайте клиент в отдельном модуле приложения, а init() вызывайте из точки монтирования или из эффекта, который выполняется только в браузере. Для Next.js это компонент с директивой 'use client', для Nuxt — плагин с суффиксом .client, для SvelteKit — ветка под проверкой окружения.

Дополнительные модули

Автосбор, записи сессий, диагностика и выбор элементов не включаются сами: их нужно импортировать явно и передать в init(). Точка входа пакета никогда не создаёт удалённых <script>-элементов, а серверная конфигурация может только сузить локально разрешённый набор возможностей, но не расширить его.

Зарезервированные имена

Пространство pp.* принадлежит ActionPulse: публичный track() такие имена отклоняет. Это те самые встроенные события, которые SDK отправляет сам, — просмотры страниц, клики, прокрутка, разделы, формы.

Что делать сейчас

1. Подключите тег скрипта — он использует тот же движок и тот же браузерный токен.
2. Держите вызовы аналитики за тонкой обёрткой в своём коде: когда пакет появится, поменяется только реализация обёртки.
3. Подтверждённые бизнес-события с самого начала отправляйте с бэкенда — этот путь не зависит от публикации пакета и не меняется.