JavaScript SDK — интеграция на сайт

Установка JS SDK Trigly: отслеживание событий, идентификация пользователей, push-уведомления.

Обзор JavaScript SDK

Trigly JavaScript SDK позволяет:

  • Отслеживать события и действия пользователей на сайте
  • Идентифицировать пользователей и обогащать профили
  • Подписывать на Web Push уведомления
  • Отображать виджеты подписки на каналы
  • Записывать e-commerce события (покупки, корзина, просмотры)

SDK работает через публичные эндпоинты Trigly API, авторизация — по API-ключу.

Установка

Шаг 1: Получение API-ключа

Создайте API-ключ через API или интерфейс Trigly:

curl -X POST https://api.trigly.ru/api/v1/cdp/api-keys \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Основной сайт"}'

Сохраните значение api_key из ответа.

Шаг 2: Подключение скрипта

Вставьте код инициализации SDK перед закрывающим тегом </body>:

<script>
(function(t,r,i,g,l,y){
  t.TriglyQueue=t.TriglyQueue||[];
  t.trigly=t.trigly||function(){t.TriglyQueue.push(arguments)};
  t.trigly.l=Date.now();
  y=r.createElement(i);y.async=1;y.src=g;
  l=r.getElementsByTagName(i)[0];l.parentNode.insertBefore(y,l);
})(window,document,'script','https://cdn.trigly.ru/sdk/v1/trigly.min.js');

trigly('init', {
  apiKey: 'tgl_live_abc123def456...',
  apiUrl: 'https://api.trigly.ru',
  // Опциональные настройки:
  autoTrackPageViews: true,     // Автоматический трекинг page_view
  autoTrackClicks: false,       // Трекинг кликов по ссылкам
  cookieDomain: '.myshop.ru',   // Домен для cookie
  sessionTimeout: 30,           // Таймаут сессии в минутах
  debug: false                  // Логирование в консоль
});
</script>

Шаг 3: Проверка установки

Откройте консоль браузера (F12) и выполните:

trigly('debug', true);
trigly('track', 'test_event', { source: 'manual' });

В консоли должно появиться сообщение об успешной отправке события.

Отслеживание событий

Базовый трекинг

trigly('track', 'event_name', {
  // произвольные свойства
  property1: 'value1',
  property2: 123
});

Стандартные события

Trigly распознаёт следующие стандартные события и использует их для аналитики, сегментации и предикций:

Просмотр страницы

// Автоматический трекинг (если autoTrackPageViews: true)
// или ручной:
trigly('track', 'page_view', {
  page: window.location.pathname,
  title: document.title,
  referrer: document.referrer
});

Покупка

trigly('track', 'purchase', {
  order_id: 'ORD-12345',
  amount: 4990,
  currency: 'RUB',
  products: [
    {
      sku: 'NIKE-AM90-BLK-42',
      name: 'Nike Air Max 90',
      price: 4990,
      quantity: 1,
      category: 'Кроссовки'
    }
  ],
  coupon: 'SPRING20',
  shipping: 290
});

Событие purchase с полем amount автоматически записывается в revenue в ClickHouse и используется для расчёта RFM, LTV и AI-скоринга.

Корзина

// Добавление в корзину
trigly('track', 'add_to_cart', {
  product_id: 'NIKE-AM90',
  name: 'Nike Air Max 90',
  price: 4990,
  quantity: 1,
  category: 'Кроссовки'
});

// Удаление из корзины
trigly('track', 'remove_from_cart', {
  product_id: 'NIKE-AM90'
});

// Начало оформления
trigly('track', 'checkout_started', {
  cart_total: 9980,
  items_count: 2
});

Поиск

trigly('track', 'search', {
  query: 'кроссовки nike',
  results_count: 47
});

Регистрация и авторизация

trigly('track', 'signup', {
  method: 'email',  // email, google, yandex, phone
  source: 'header_form'
});

trigly('track', 'login', {
  method: 'email'
});

Произвольные события

// Просмотр товара
trigly('track', 'product_viewed', {
  product_id: 'NIKE-AM90',
  name: 'Nike Air Max 90',
  price: 4990,
  category: 'Кроссовки',
  brand: 'Nike'
});

// Добавление в избранное
trigly('track', 'added_to_wishlist', {
  product_id: 'NIKE-AM90'
});

// Просмотр категории
trigly('track', 'category_viewed', {
  category: 'Кроссовки',
  items_shown: 24
});

// Использование промокода
trigly('track', 'coupon_applied', {
  coupon: 'SPRING20',
  discount: 998
});

// Отправка формы
trigly('track', 'form_submitted', {
  form_id: 'contact_us',
  subject: 'Вопрос о доставке'
});

// Просмотр видео
trigly('track', 'video_watched', {
  video_id: 'product-review-123',
  duration_seconds: 180,
  completed: true
});

Пакетная отправка

SDK автоматически группирует события в пакеты для оптимизации сетевых запросов. По умолчанию пакет отправляется:

  • Каждые 5 секунд
  • При накоплении 10 событий
  • При уходе пользователя со страницы (beforeunload)

Вы можете принудительно отправить все накопленные события:

trigly('flush');

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

Базовая идентификация

Привяжите действия анонимного посетителя к конкретному контакту:

trigly('identify', {
  email: 'ivan@example.com',
  first_name: 'Иван',
  last_name: 'Петров'
});

Полная идентификация

trigly('identify', {
  // Обязательные (хотя бы одно):
  email: 'ivan@example.com',
  // или phone: '+79161234567',
  // или external_id: 'user_123',

  // Опциональные:
  first_name: 'Иван',
  last_name: 'Петров',
  phone: '+79161234567',
  city: 'Москва',
  country: 'RU',
  language: 'ru',
  timezone: 'Europe/Moscow',

  // Произвольные поля:
  custom_fields: {
    plan: 'premium',
    company: 'ООО Технологии',
    registration_date: '2026-01-15',
    preferred_brand: 'Nike'
  }
});

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

  • После регистрации — привяжите email к текущей сессии
  • После авторизации — обновите данные профиля
  • При заполнении формы — когда пользователь указал email/телефон
  • При изменении профиля — обновите custom_fields
// Пример: после успешной регистрации
async function onRegistration(formData) {
  const response = await registerUser(formData);

  trigly('identify', {
    email: formData.email,
    first_name: formData.name,
    custom_fields: {
      registration_source: 'website',
      registration_date: new Date().toISOString()
    }
  });

  trigly('track', 'signup', { method: 'email' });
}

Сброс идентификации

При выходе пользователя из аккаунта сбросьте идентификацию:

trigly('reset');

Это очищает привязку и создаёт новый анонимный идентификатор сессии.

Web Push уведомления

Шаг 1: Регистрация Service Worker

Trigly предоставляет готовый Service Worker. Разместите его в корне вашего сайта:

<script>
// Регистрация SW (вызовите после init)
if ('serviceWorker' in navigator) {
  navigator.serviceWorker.register('/trigly-sw.js')
    .then(function(registration) {
      console.log('SW зарегистрирован:', registration.scope);
    })
    .catch(function(error) {
      console.error('Ошибка регистрации SW:', error);
    });
}
</script>

Получите файл Service Worker:

# Service Worker доступен по URL:
curl "https://api.trigly.ru/api/v1/sdk/push/sw.js" -o public/trigly-sw.js

Содержимое Service Worker обрабатывает:

  • Получение push-уведомлений
  • Отображение нотификации (title, body, icon, image)
  • Клик по уведомлению — переход по URL из payload

Шаг 2: Запрос разрешения и подписка

async function subscribeToPush() {
  // 1. Запрос разрешения
  const permission = await Notification.requestPermission();
  if (permission !== 'granted') {
    console.log('Пользователь отклонил push-уведомления');
    return;
  }

  // 2. Получение VAPID-ключа от Trigly
  const response = await fetch(
    'https://api.trigly.ru/api/v1/sdk/push/vapid-key?org_id=ORG_ID'
  );
  const { vapid_key } = await response.json();

  // 3. Подписка через Push API
  const registration = await navigator.serviceWorker.ready;
  const subscription = await registration.pushManager.subscribe({
    userVisibleOnly: true,
    applicationServerKey: urlBase64ToUint8Array(vapid_key)
  });

  // 4. Отправка подписки в Trigly
  await fetch(
    'https://api.trigly.ru/api/v1/sdk/push/subscribe?org_id=ORG_ID',
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        customer_id: 'CUSTOMER_UUID',  // или email
        subscription: subscription.toJSON()
      })
    }
  );

  console.log('Подписка на push оформлена!');
}

// Вспомогательная функция
function urlBase64ToUint8Array(base64String) {
  const padding = '='.repeat((4 - base64String.length % 4) % 4);
  const base64 = (base64String + padding)
    .replace(/-/g, '+')
    .replace(/_/g, '/');
  const rawData = window.atob(base64);
  const outputArray = new Uint8Array(rawData.length);
  for (let i = 0; i < rawData.length; ++i) {
    outputArray[i] = rawData.charCodeAt(i);
  }
  return outputArray;
}

Шаг 3: Отписка

async function unsubscribeFromPush() {
  const registration = await navigator.serviceWorker.ready;
  const subscription = await registration.pushManager.getSubscription();

  if (subscription) {
    await subscription.unsubscribe();

    await fetch(
      'https://api.trigly.ru/api/v1/sdk/push/unsubscribe?org_id=ORG_ID',
      {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          customer_id: 'CUSTOMER_UUID',
          endpoint: subscription.endpoint
        })
      }
    );
  }
}

Отправка Push через API

После подписки вы можете отправлять push через кампании или напрямую:

# Через кампанию
curl -X POST https://api.trigly.ru/api/v1/campaigns \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Flash sale Push",
    "channel": "push",
    "campaign_type": "one_time",
    "segment_id": "SEGMENT_ID",
    "subject": "Скидки 50% только сегодня!",
    "template_id": "PUSH_TEMPLATE_ID"
  }'

Формат push-уведомления:

{
  "title": "Скидки 50%!",
  "body": "Только сегодня на все кроссовки. Промокод FLASH50",
  "icon": "https://myshop.ru/icon-192.png",
  "url": "https://myshop.ru/sale"
}

Ограничения: title — макс. 50 символов, body — макс. 100 символов.

Виджеты подписки

Trigly предоставляет готовые виджеты для подписки посетителей на каналы.

Получение виджетов

// SDK автоматически загружает и отображает активные виджеты
trigly('widgets', {
  position: 'bottom-right',  // bottom-left, top-right, top-left
  delay: 5000,               // Задержка показа (мс)
  showOnScroll: 50           // Показать при прокрутке до 50%
});

Типы виджетов

Тип Описание
popup Всплывающее окно по центру
inline Встроенный блок (для встраивания в HTML)
floating Плавающая кнопка (bottom-right)

Создание виджета через API

curl -X POST https://api.trigly.ru/api/v1/channels/config/widgets \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Подписка на рассылку",
    "widget_type": "popup",
    "channels": ["email", "telegram", "push"],
    "design": {
      "title": "Подпишитесь на скидки!",
      "subtitle": "Получайте персональные предложения первыми",
      "button_text": "Подписаться",
      "primary_color": "#10b981",
      "position": "center"
    },
    "targeting_rules": {
      "pages": ["/", "/products/*"],
      "delay_seconds": 10,
      "scroll_percent": 30,
      "show_once_per_session": true
    },
    "is_active": true
  }'

Подписка через виджет (SDK-эндпоинт)

// SDK вызывает этот эндпоинт автоматически при клике "Подписаться"
fetch('https://api.trigly.ru/api/v1/sdk/channels/subscribe?org_id=ORG_ID', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'user@example.com',
    channels: ['email', 'telegram'],
    source: 'widget',
    widget_id: 'WIDGET_UUID'
  })
});

Ответ включает Telegram-ссылку для привязки, если выбран канал Telegram:

{
  "customer_id": "new-customer-uuid",
  "channels_subscribed": ["email"],
  "telegram_link": "https://t.me/your_bot?start=abc123..."
}

Аналитика виджетов

# Статистика виджета
curl https://api.trigly.ru/api/v1/channels/config/widgets/WIDGET_ID \
  -H "Authorization: Bearer $TOKEN"

# Ответ включает:
# "total_views": 12345,
# "total_subscriptions": 567,
# "conversion_rate": 4.59

API Reference (HTTP-эндпоинты)

Все SDK-эндпоинты доступны без JWT-авторизации. Авторизация через API-ключ в заголовке X-API-Key (для track/identify/batch) или через query-параметр org_id (для push/widgets).

Track

POST /api/v1/sdk/track
Header: X-API-Key: tgl_live_...

{
  "customer_id": "uuid",
  "event_name": "purchase",
  "properties": {"amount": 4990},
  "page_url": "https://...",
  "referrer": "https://...",
  "session_id": "session_abc"
}

Batch

POST /api/v1/sdk/batch
Header: X-API-Key: tgl_live_...

{
  "events": [
    {"customer_id": "id1", "event_name": "page_view", "properties": {}},
    {"customer_id": "id1", "event_name": "click", "properties": {"element": "buy_btn"}}
  ]
}

Максимум 100 событий в одном batch-запросе.

Identify

POST /api/v1/sdk/identify
Header: X-API-Key: tgl_live_...

{
  "email": "user@example.com",
  "first_name": "Иван",
  "phone": "+79161234567",
  "custom_fields": {"plan": "premium"}
}

Частые вопросы

Как отслеживать SPA-приложения?

Для React/Vue/Angular-приложений интегрируйте трекинг в роутер:

// React Router пример
import { useEffect } from 'react';
import { useLocation } from 'react-router-dom';

function usePageTracking() {
  const location = useLocation();

  useEffect(() => {
    trigly('track', 'page_view', {
      page: location.pathname,
      search: location.search
    });
  }, [location]);
}

Как работать с серверным рендерингом (SSR)?

SDK работает только в браузере. Для серверного трекинга используйте HTTP API напрямую:

// Node.js / Next.js серверный трекинг
import fetch from 'node-fetch';

export async function trackServerEvent(customerId, eventName, properties) {
  await fetch('https://api.trigly.ru/api/v1/sdk/track', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.TRIGLY_API_KEY
    },
    body: JSON.stringify({
      customer_id: customerId,
      event_name: eventName,
      properties
    })
  });
}

Как тестировать в dev-окружении?

trigly('init', {
  apiKey: 'tgl_test_...',          // Тестовый API-ключ
  apiUrl: 'http://localhost:8000', // Локальный сервер
  debug: true                     // Логирование в консоль
});

Влияет ли SDK на производительность сайта?

  • Скрипт загружается асинхронно (async) — не блокирует рендеринг
  • Размер SDK: ~8 KB (gzip)
  • События отправляются пакетами, не на каждое действие
  • Используется navigator.sendBeacon() при уходе со страницы

Совместим ли SDK с Content Security Policy (CSP)?

Добавьте в CSP:

script-src 'self' https://cdn.trigly.ru;
connect-src 'self' https://api.trigly.ru;

Полный пример интеграции

<!DOCTYPE html>
<html lang="ru">
<head>
  <meta charset="UTF-8">
  <title>Мой магазин</title>
</head>
<body>
  <!-- Контент страницы -->

  <!-- Trigly SDK -->
  <script>
  (function(t,r,i,g,l,y){
    t.TriglyQueue=t.TriglyQueue||[];
    t.trigly=t.trigly||function(){t.TriglyQueue.push(arguments)};
    t.trigly.l=Date.now();
    y=r.createElement(i);y.async=1;y.src=g;
    l=r.getElementsByTagName(i)[0];l.parentNode.insertBefore(y,l);
  })(window,document,'script','https://cdn.trigly.ru/sdk/v1/trigly.min.js');

  // Инициализация
  trigly('init', {
    apiKey: 'tgl_live_abc123...',
    apiUrl: 'https://api.trigly.ru',
    autoTrackPageViews: true
  });

  // Идентификация (если пользователь авторизован)
  var user = getCurrentUser(); // ваша функция
  if (user) {
    trigly('identify', {
      email: user.email,
      first_name: user.name,
      custom_fields: { user_id: user.id }
    });
  }

  // Виджеты подписки
  trigly('widgets', { delay: 5000 });
  </script>

  <!-- Отслеживание покупки (на странице Thank You) -->
  <script>
  if (window.orderData) {
    trigly('track', 'purchase', {
      order_id: window.orderData.id,
      amount: window.orderData.total,
      currency: 'RUB',
      products: window.orderData.items
    });
  }
  </script>
</body>
</html>
Назад
Rate Limits
Далее
Webhooks

Не нашли ответ?

Swagger UI с интерактивной документацией и поддержка в Telegram.

Swagger UIНаписать в поддержку