Help

Это руководство описывает установку и использование Clickstream SDK от SurveyAnalytica в веб-проектах. SDK опубликован в npm и работает в любой среде JavaScript, включая Vanilla JS, Next.js и React. Для мобильных приложений см. руководство по мобильным SDK.

Прежде чем начать, выполните настройку workflow, чтобы получить API Key и Endpoint URL.

Установка

Vanilla JS / HTML-сайты

Подключите UMD-бандл прямо на странице. Сборка не требуется.

<script src="https://cdn.jsdelivr.net/npm/@surveyanalytica/clickstream-web/dist/index.umd.js"></script>
<script>
  SAClickstream.init('YOUR_WORKFLOW_ID', 'YOUR_API_KEY', {
    endpoint: 'YOUR_ENDPOINT_URL'
  });
</script>

npm-проекты (Next.js, React и т. д.)

npm install @surveyanalytica/clickstream-web

Затем выполните инициализацию один раз, в точке входа вашего приложения:

import { SAClickstream } from '@surveyanalytica/clickstream-web';

SAClickstream.init('YOUR_WORKFLOW_ID', 'YOUR_API_KEY', {
  endpoint: 'YOUR_ENDPOINT_URL'
});

Для Next.js вызывайте init внутри Client Component или в _app.js / layout.js. SDK безопасен для server-side rendering — весь доступ к браузерным API защищён внутренними проверками.

Отслеживание просмотров страниц

SDK автоматически отслеживает просмотры страниц. При каждом изменении URL (включая навигацию в рамках single-page приложения через History API) отправляется событие page_view с текущим URL, заголовком страницы и referrer. Никакого дополнительного кода, кроме вызова init, не требуется.

Чтобы отправить просмотр страницы вручную:

SAClickstream.page('/checkout', { campaign: 'summer-sale' });

Отслеживание пользовательских событий

SAClickstream.track('button_clicked', {
  label: 'Buy Now',
  productId: 'sku-9821',
  price: 49.99
});

Значения свойств могут быть строками, числами, булевыми значениями или вложенными объектами. Используйте короткие и единообразные названия событий по всему кодовой базе (например, всегда button_clicked, а не смесь buttonClick и btn_tap).

Идентификация пользователей после входа

До входа в систему SDK присваивает каждому посетителю случайный анонимный ID, сохранённый в localStorage. После входа вызовите identify с ID контакта из вашего бэкенда:

// After a successful login
SAClickstream.identify('contact-id-from-your-backend');

Это отправляет событие uid_transition, связывающее анонимную сессию с известным контактом. События, зафиксированные до входа, связываются с контактом через анонимный ID, сохранённый в записи контакта, — данные не теряются.

Если на вашем сайте используется баннер согласия на использование cookie, учитывайте выбор пользователя’я:

// User accepted tracking
SAClickstream.setConsent(true);

// User declined tracking
SAClickstream.setConsent(false);

Когда consent установлен в false, отслеживание немедленно прекращается, а связь с анонимным ID сбрасывается. Новые события не отправляются до повторного предоставления согласия.

Как отправляются события

SDK группирует события в пакеты и отправляет их каждые 500 миллисекунд либо сразу, как только в очереди накопится 20 событий. Неудачные запросы повторяются до трёх раз с увеличивающейся задержкой. Это снижает нагрузку на сеть, не теряя события при временных проблемах с подключением.

Устранение неполадок

События не появляются в моём workflow

Убедитесь, что workflow находится в состоянии Active.
Проверьте консоль браузера на наличие сетевых ошибок при запросах к вашему endpoint URL.
Убедитесь, что API Key совпадает с KEY, указанным в панели триггера, — скопируйте и вставьте значение, а не вводите его вручную.
Убедитесь, что init вызывается до любых вызовов track или page.

Записываются дублирующиеся просмотры страниц

Если вы вызываете SAClickstream.page() вручную в дополнение к автоматическому отслеживанию, на каждую навигацию будет приходиться два события. Либо отключите автоматическое отслеживание (autoPage: false в опциях init), либо удалите свои ручные вызовы page().

We use cookies