Как настроить API-ключи и JavaScript SDK в Trigly

Сбор данных о поведении пользователей на сайте — фундамент персонализации и автоматизации маркетинга. Без трекинга событий невозможно запустить триггерные цепочки, рассчитать RFM-скоринг или построить предиктивные модели. В этом руководстве мы настроим API-ключи Trigly и JavaScript SDK для полноценного сбора данных.

Архитектура трекинга в Trigly

Прежде чем приступить к настройке, важно понять, как устроен сбор данных:

1. JavaScript SDK на вашем сайте отправляет события в Trigly через публичный API (/api/v1/sdk/track).
2. События сохраняются в ClickHouse — колоночную базу данных, оптимизированную для аналитики. Хранение — 365 дней.
3. Профили пользователей обогащаются в CDP (PostgreSQL) — при каждом событии обновляются поля last_activity_at, total_revenue, total_orders и другие.
4. Триггеры и потоки реагируют на события в реальном времени.

SDK использует публичный API-ключ, который безопасно размещать в клиентском коде. Rate limit для SDK-эндпоинтов: 1000 запросов в минуту.

Шаг 1: Создайте API-ключ

Перейдите в CDP, затем в API Keys и нажмите "Создать":

1. Название: укажите понятное имя, например "Production Website" или "Staging App".
2. Тип: SDK (публичный ключ для клиентского JavaScript-кода).

После создания API-ключ отображается один раз. Скопируйте его и сохраните в безопасном месте (менеджер паролей, переменные окружения CI/CD). Если ключ потерян, отзовите старый и создайте новый.

Совет: Создайте отдельные ключи для разных окружений: production, staging, development. Это позволит отслеживать источник данных и безопасно отзывать ключи без влияния на продакшн.

Частые ошибки при работе с API-ключами:

• Хранение ключа в публичном git-репозитории — используйте переменные окружения.
• Использование одного ключа для всех проектов — при компрометации придется менять везде.
• Забывают отозвать неиспользуемые ключи — проводите ревизию ключей раз в квартал.

Шаг 2: Установите JavaScript SDK

Добавьте следующий код перед закрывающим тегом </body> на каждой странице сайта. Если вы используете SPA-фреймворк (React, Vue, Next.js), добавьте в корневой компонент.

<script>
  !function(){var t=window.trigly=window.trigly||[];t.methods=["track","identify","page"];
  t.factory=function(e){return function(){var n=Array.prototype.slice.call(arguments);
  n.unshift(e);t.push(n);return t}};for(var e=0;e<t.methods.length;e++){
  var n=t.methods[e];t[n]=t.factory(n)}}();
</script>
<script async src="https://api.trigly.ru/api/v1/sdk/trigly.js?key=YOUR_API_KEY"></script>

Замените YOUR_API_KEY на ваш ключ из шага 1.

SDK загружается асинхронно (атрибут async), поэтому не блокирует рендеринг страницы. До загрузки основного скрипта все вызовы trigly.track() и trigly.identify() буферизируются в массив и выполняются после инициализации.

Проверка установки

Откройте DevTools браузера (F12), вкладку Network. После загрузки страницы вы должны увидеть запрос к api.trigly.ru. В Console введите window.trigly — объект должен быть определен.

Шаг 3: Трекинг событий

После установки SDK начните отправлять события. Каждое событие содержит: имя (event_name), свойства (properties) и автоматически добавленные поля (page_url, referrer, session_id).

Основные e-commerce события

// Просмотр товара
trigly.track('product_viewed', {
  product_id: 'sku-123',
  product_name: 'Кроссовки Nike Air Max',
  price: 7990,
  category: 'Обувь',
  brand: 'Nike'
});

// Добавление в корзину
trigly.track('cart_add', {
  product_id: 'sku-123',
  quantity: 1,
  cart_total: 7990
});

// Удаление из корзины
trigly.track('cart_remove', {
  product_id: 'sku-123'
});

// Покупка
trigly.track('purchase', {
  order_id: 'ord-456',
  revenue: 7990,
  items: ['sku-123'],
  payment_method: 'card'
});

// Брошенная корзина
trigly.track('cart_abandoned', {
  cart_total: 7990,
  items: ['Кроссовки Nike Air Max'],
  cart_url: window.location.href
});

Общие события

// Просмотр страницы (для SPA-приложений)
trigly.page();

// Подписка на рассылку
trigly.track('newsletter_subscribe', {
  source: 'footer_form',
  email: 'user@example.com'
});

// Поиск на сайте
trigly.track('search', {
  query: 'кроссовки',
  results_count: 42
});

Совет: Зарегистрируйте стандартные события в разделе CDP, далее Определения событий. Trigly предоставляет 10+ системных типов событий и позволяет создавать собственные. Определения помогают валидировать данные и строить отчеты.

Лучшие практики трекинга

1. Используйте snake_case для имен событий: product_viewed, а не ProductViewed или product-viewed.
2. Передавайте revenue в числовом формате (не строкой): revenue: 7990, не revenue: "7990 руб.".
3. Не отправляйте персональные данные (пароли, номера карт) в свойствах событий.
4. Группируйте связанные события через session_id — SDK делает это автоматически.
5. Батчевая отправка: для высоконагруженных страниц (каталог, поиск) используйте серверный API /api/v1/sdk/batch для отправки нескольких событий одним запросом.

Шаг 4: Идентификация пользователей

Пока пользователь не идентифицирован, Trigly создает анонимный профиль по session_id. Когда пользователь логинится или регистрируется, вызовите identify для связывания:

// После логина или регистрации
trigly.identify('user_123', {
  email: 'ivan@example.com',
  first_name: 'Иван',
  last_name: 'Петров',
  phone: '+79001234567',
  city: 'Москва'
});

Первый аргумент — уникальный external_id пользователя в вашей системе. Второй — объект с полями профиля. Trigly найдет или создаст контакт в CDP и свяжет все предыдущие анонимные события с этим профилем.

Когда вызывать identify:

• После успешного логина
• После регистрации
• После оформления заказа (если пользователь указал email)
• При каждом посещении, если пользователь уже авторизован

Частые ошибки при идентификации:

• Вызов identify без external_id — обязательный параметр, используйте ID из вашей базы.
• Передача разных external_id для одного пользователя — приведет к дублированию. Используйте объединение контактов для исправления.
• Вызов identify при каждом событии — достаточно одного вызова на сессию.

Шаг 5: Серверный API (для продвинутых)

Помимо JavaScript SDK, Trigly предоставляет серверный API для отправки событий с бэкенда:

curl -X POST https://api.trigly.ru/api/v1/sdk/track \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "user_123",
    "event_type": "custom",
    "event_name": "order_shipped",
    "properties": {"order_id": "ord-456", "tracking_number": "EMS123456"}
  }'

Серверный API полезен для:

• Событий, которые происходят на бэкенде (оплата, возврат, доставка)
• Импорта исторических данных
• Интеграций с CRM и ERP

Что происходит после настройки

После установки SDK и начала сбора данных:

1. ClickHouse накапливает историю событий — они доступны в аналитике через 5-10 секунд после отправки.
2. Профили CDP обогащаются автоматически: обновляются last_activity_at, считаются total_orders и total_revenue.
3. RFM-скоринг пересчитывается ежедневно в 3:00 на основе событий покупок.
4. AI-скоринг оценивает каждого клиента (0-100) на основе поведенческих данных.
5. Динамические сегменты обновляются каждые 30 минут с учетом новых событий.
6. Триггерные цепочки реагируют на события в реальном времени — например, брошенная корзина.
7. Предиктивные модели (churn, LTV, next purchase) обучаются на накопленных данных.

Часто задаваемые вопросы

Влияет ли SDK на скорость загрузки сайта? Нет. SDK загружается асинхронно и весит менее 5 КБ. Все вызовы буферизируются до загрузки, поэтому вы можете вызывать trigly.track() сразу, не дожидаясь инициализации.

Что делать, если данные не поступают? Проверьте: 1) API-ключ корректен и не отозван, 2) нет блокировки запросов к api.trigly.ru (ad-blockers, CSP), 3) в DevTools Network нет ошибок 401/429. Rate limit для SDK: 1000 запросов/минуту.

Можно ли использовать SDK на мобильном приложении? JavaScript SDK предназначен для веб-сайтов. Для мобильных приложений используйте серверный REST API (/api/v1/sdk/track и /api/v1/sdk/identify) напрямую из вашего мобильного бэкенда.

---

Итог

Настройка API-ключей и JavaScript SDK — это инвестиция в фундамент, на котором строятся все остальные возможности Trigly: триггерные цепочки, RFM-анализ, AI-скоринг и предиктивные модели. Без данных о поведении пользователей эти инструменты работают вхолостую. Установите SDK на все страницы сайта, определите 5-10 ключевых бизнес-событий, настройте identify для связывания анонимных визитов с профилями — и через 2-3 недели у вас будет достаточно данных для полноценной аналитики и персонализации. Весь процесс занимает 1-2 часа работы разработчика. Чем раньше вы начнёте собирать данные, тем быстрее ML-модели выйдут на рабочую точность — для предсказания оттока и LTV требуется минимум 3 месяца истории событий. Рекомендуем начать с пяти базовых событий — page_view, product_viewed, cart_add, purchase и signup — этого достаточно для RFM-анализа, триггерных цепочек и первых предиктивных моделей.

---

Попробуйте Trigly бесплатно и начните собирать данные о поведении пользователей уже сегодня. Регистрация на trigly.ru/register.