К содержанию
ActionPulse

Подключение скриптом

Один тег в разметке сайта: версионный URL с проверкой целостности, атрибуты data-token и data-consent, подключение через тег-менеджер и совместимый быстрый путь.

Кому
Тем, у кого есть доступ к HTML или тег-менеджеру
Проверено
На этой странице

Скрипт — самый быстрый способ начать собирать поведение в браузере. Он не требует сборки, работает на любой CMS и подключается через тег-менеджер.

Рекомендуемый вариант для production

Зафиксируйте версию и проверьте целостность файла:

<script
  src="https://YOUR_ACTIONPULSE_HOST/v1/sdk/browser/0.6.0/tracker.js"
  integrity="SRI_FROM_MANIFEST"
  crossorigin="anonymous"
  data-token="YOUR_BROWSER_TOKEN"
  data-consent="required"
></script>

Что здесь важно:

  • /v1/sdk/browser/0.6.0/tracker.js — неизменяемый адрес конкретной версии. Содержимое по этому адресу не меняется, поэтому его можно кэшировать надолго и зафиксировать в политике безопасности.
  • integrity — контрольная сумма sha384. Браузер откажется исполнять файл, если байты не совпали.
  • crossorigin="anonymous" — обязателен вместе с integrity, когда файл загружается с другого домена. Без него браузер не сможет проверить сумму.
  • data-token — ваш браузерный токен. Совместимое имя data-key тоже работает; если указать оба с разными значениями, скрипт не запустится.
  • data-consent="required" — сбор ждёт явного решения посетителя.

Манифест версии

По адресу https://YOUR_ACTIONPULSE_HOST/v1/sdk/browser/0.6.0/manifest.json лежит описание всех файлов версии 0.6.0: размер, SHA-256, SHA-384 и готовое значение integrity. Манифест отдаётся без авторизации — его удобно читать из скрипта деплоя.

{
  "schema_version": 1,
  "package": "@actionpulse/browser",
  "version": "0.6.0",
  "assets": {
    "core": {
      "file": "sdk/browser/0.6.0/tracker.js",
      "path": "/v1/sdk/browser/0.6.0/tracker.js",
      "bytes": 21161,
      "gzip_bytes": 7642,
      "sha256": "…",
      "sha384": "…",
      "integrity": "sha384-…"
    }
  }
}

Значения размеров и сумм приведены как пример формата — берите свои из своей установки.

Совместимый быстрый путь

Если фиксировать версию пока не нужно, работает короткий вариант:

<script
  src="https://YOUR_ACTIONPULSE_HOST/v1/t.js"
  data-token="YOUR_BROWSER_TOKEN"
  data-consent="required"
></script>

/v1/t.js сохраняется как совместимый маршрут. Байты здесь те же, что и у версионного файла, но адрес не привязан к версии: проверку целостности к нему применить нельзя, и кэшируется он на час, а не навсегда. Для production со строгой политикой безопасности используйте версионный URL.

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

Атрибут Назначение
data-token Браузерный токен pp_bt_…
data-key То же самое, совместимое имя; поддерживает legacy-ключи pp_wk_…
data-consent required — не собирать до явного согласия
data-api-host Куда отправлять события, если это не origin самого скрипта
data-asset-host Откуда грузить дополнительные модули, если это не каталог скрипта

Без data-api-host события уходят на origin, с которого загружен скрипт. Это то, что нужно в обычной установке.

Тег-менеджер и CMS

В Google Tag Manager, «Яндекс Метрике» и подобных системах создайте тег типа «Пользовательский HTML», вставьте туда тег скрипта и настройте срабатывание на всех страницах.

Если тег-менеджер подключается асинхронно и вы используете data-consent, убедитесь, что вызовы согласия происходят после загрузки скрипта — проверяйте наличие window.pp перед вызовом.

Согласие

С data-consent="required" до решения посетителя скрипт полностью пассивен: не создаёт идентификаторов, не читает и не пишет хранилище браузера, не ставит обработчики и не отправляет ни одного запроса.

// посетитель согласился
pp.setConsent('granted');

// посетитель отказался
pp.setConsent('denied');

// посетитель отозвал согласие позже
pp.setConsent('revoked');

Если атрибута data-consent нет вообще, сбор начинается сразу при загрузке. Это осознанный выбор, а не значение по умолчанию «на всякий случай»: указывайте data-consent="required" везде, где посетителю нужно дать выбор.

Отправка своих событий

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

Имена вроде payment_succeeded, order_paid, order_created, refund, registered браузеру недоступны в принципе: они принимаются только с серверным ключом. Это не настройка, а граница доверия — их отправляют с бэкенда.

Разрешённые домены

Браузерный токен работает только с тех origin, которые перечислены при его выпуске: точная схема, хост и порт, без масок и путей. Запрос с другого адреса получит 403 с кодом credential_origin_forbidden.

Список origin задаётся в момент выпуска токена и после этого не редактируется. Чтобы изменить набор доменов, выпустите новый токен и замените значение в теге.

Политика безопасности контента

Если на сайте настроен CSP, разрешите:

Директива Значение Зачем
script-src origin, с которого грузится скрипт загрузка tracker.js и его модулей
connect-src origin приёма событий отправка событий
worker-src blob: только для записи сессий

unsafe-eval не требуется никогда: в бандлах нет ни eval, ни new Function.

Про worker-src легко забыть, а симптом обманчив: без него перестают работать только записи сессий, а просмотры страниц, идентификация, автосбор и диагностика продолжают идти как ни в чём не бывало.

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

Записи сессий, диагностика и выбор элементов подключаются отдельными файлами той же версии. Ядро подгружает их само с проверкой целостности: адреса и суммы вшиты в него на этапе сборки.

Модули берутся с origin самого скрипта, а не с адреса приёма событий. Если файл недоступен или его сумма не совпала, соответствующая возможность просто не включится — базовый сбор при этом продолжает работать.

Проверка

  1. Откройте страницу и подтвердите согласие.
  2. В консоли браузера вызовите pp.track('signup_completed', { plan: 'pro' }).
  3. Во вкладке «Сеть» найдите запрос на /v1/track — ожидаемый ответ 202 Accepted.
  4. В ActionPulse откройте Данные и сбор → События.

Если что-то пошло не так — дерево диагностики разбирает типовые причины по порядку.