Інтеграція Segment CDP на сайт

Інтеграція Segment CDP

Segment — Customer Data Platform: єдина точка збору подій, яка маршрутизує їх до десятків інструментів одночасно. Замість того щоб ставити Mixpanel, Amplitude, Intercom та Braze окремо, підключуєте один SDK та через UI настроюєте destinations. Ключові концепції — Sources (звідки), Destinations (куди), Protocols (контракт даних).

Архітектура

Браузер / Сервер / Мобіль
         │
    Segment Analytics.js / Node SDK
         │
    ┌────┴─────────────────────────┐
    │         Segment              │
    │  Sources → Protocols → ...   │
    └────┬─────────────────────────┘
         │
    ┌────┴──────────────────────────────────────────┐
    │  Destinations                                  │
    │  ├── Mixpanel (event analytics)               │
    │  ├── Amplitude (product analytics)            │
    │  ├── BigQuery (data warehouse)                │
    │  ├── Intercom (customer messaging)            │
    │  ├── Braze (marketing automation)             │
    │  ├── HubSpot (CRM)                           │
    │  └── Webhook (custom)                        │
    └───────────────────────────────────────────────┘

Встановлення Analytics.js 2.0

npm install @segment/analytics-next

// src/analytics/segment.ts
import { AnalyticsBrowser } from '@segment/analytics-next';

export const analytics = AnalyticsBrowser.load({
  writeKey: import.meta.env.VITE_SEGMENT_WRITE_KEY,
  cdnURL: undefined, // користувацький proxy опціонально
}, {
  integrations: {
    'All': true,
    'Segment.io': {
      deliveryStrategy: {
        strategy: 'batching',
        config: {
          size: 10,
          timeout: 5000,
        },
      },
    },
  },
});

export default analytics;

CDN без бандлера:

<script>
!function(){var i="analytics",analytics=window[i]=window[i]||[];if(!analytics.initialize)if(analytics.invoked)window.console&&console.error&&console.error("Segment snippet included twice.");else{analytics.invoked=!0;analytics.methods=["trackSubmit","trackClick","trackLink","trackForm","pageview","identify","reset","group","track","ready","alias","debug","page","once","off","on","addSourceMiddleware","addIntegrationMiddleware","setAnonymousId","addDestinationMiddleware","register"];analytics.factory=function(e){return function(){if(window[i].initialized)return window[i][e].apply(window[i],arguments);var n=Array.prototype.slice.call(arguments);if(["track","screen","alias","group","page","identify"].indexOf(e)>-1){var c=document.querySelector("link[rel='canonical']");n.push({__t:"bpc",c:c&&c.getAttribute("href")||void 0,p:location.pathname,u:location.href,s:location.search,t:document.title,r:document.referrer})}n.unshift(e);analytics.push(n);return analytics}};for(var n=0;n<analytics.methods.length;n++){var key=analytics.methods[n];analytics[key]=analytics.factory(key)}analytics.load=function(key,n){var t=document.createElement("script");t.type="text/javascript";t.async=!0;t.setAttribute("data-global-segment-analytics-key",i);t.src="https://cdn.segment.com/analytics.js/v1/"+key+"/analytics.min.js";var r=document.getElementsByTagName("script")[0];r.parentNode.insertBefore(t,r);analytics._writeKey=key;analytics._loadOptions=n};analytics.SNIPPET_VERSION="5.2.1";
analytics.load("YOUR_WRITE_KEY");
analytics.page();
}}();
</script>

Основні методи

Page

// Автоматично — явно називаємо для SPA
analytics.page('Product', 'Listing', {
  url: window.location.href,
  path: window.location.pathname,
  title: document.title,
  referrer: document.referrer,
  search: window.location.search,
  // користувацькі властивості
  category: 'electronics',
  locale: 'ru-RU',
});

Track

analytics.track('Order Completed', {
  order_id: 'ORDER-789',
  affiliation: 'Web Store',
  total: 14500,
  subtotal: 13500,
  revenue: 14500,
  shipping: 500,
  tax: 500,
  discount: 0,
  currency: 'RUB',
  products: [
    {
      product_id: 'SKU-001',
      sku: 'SKU-001',
      name: 'Professional Plan',
      price: 13500,
      quantity: 1,
      category: 'subscription',
    },
  ],
});

Segment дотримується ecommerce spec — якщо називати eventi за специфікацією, вони автоматично映射ються в Destinations без додаткової настройки.

Identify

analytics.identify('usr_12345', {
  email: '[email protected]',
  name: 'Іван Петров',
  plan: 'pro',
  company: {
    id: 'company_abc',
    name: 'ООО Приклад',
  },
  createdAt: '2024-01-15T10:00:00Z',
  // Trait-и, специфічні для вашого продукту
  projects_count: 5,
  last_login: new Date().toISOString(),
});

Group

// Привязати користувача до організації (B2B)
analytics.group('company_abc', {
  name: 'ООО Приклад',
  industry: 'Technology',
  employees: 25,
  plan: 'enterprise',
  website: 'https://example.com',
});

Middleware для збагачення подій

// Додаємо контекст до всіх подій
analytics.addSourceMiddleware(({ payload, next }) => {
  // Додати версію додатка
  payload.obj.context = {
    ...payload.obj.context,
    app: {
      version: APP_VERSION,
    },
    locale: navigator.language,
  };

  // Додати AB-варіант
  const abVariant = localStorage.getItem('ab_variant');
  if (abVariant && payload.obj.properties) {
    payload.obj.properties.ab_variant = abVariant;
  }

  next(payload);
});

Server-side джерело (Node.js / PHP)

Для подій, які неможна трекати з фронту (webhook-оплата, активація підписки):

// Node.js
import { Analytics } from '@segment/analytics-node';

const analytics = new Analytics({
  writeKey: process.env.SEGMENT_SERVER_WRITE_KEY,
  flushAt: 20,
  flushInterval: 10000,
});

// Подія оплати від платіжного шлюзу
analytics.track({
  userId: 'usr_12345',
  event: 'Subscription Started',
  properties: {
    plan: 'pro',
    revenue: 2990,
    currency: 'RUB',
    billing_cycle: 'monthly',
    payment_method: 'card',
    mrr: 2990,
  },
  context: {
    ip: clientIp,
  },
});

// Обов'язково викликати flush перед завершенням процесу
process.on('SIGTERM', async () => {
  await analytics.closeAndFlush({ timeout: 5000 });
  process.exit(0);
});

// PHP через HTTP API
class SegmentService
{
    private string $writeKey;
    private string $endpoint = 'https://api.segment.io/v1/track';

    public function track(string $userId, string $event, array $properties = []): void
    {
        Http::withBasicAuth($this->writeKey, '')
            ->timeout(3)
            ->post($this->endpoint, [
                'userId'     => $userId,
                'event'      => $event,
                'properties' => $properties,
                'timestamp'  => now()->toIso8601String(),
                'messageId'  => uniqid('php_', true),
                'context'    => ['library' => ['name' => 'analytics-php']],
            ]);
    }
}

Protocols: контракт даних

Segment Protocols дозволяє задати JSON Schema для кожної події — порушення схеми логуються та блокуються:

{
  "name": "Order Completed",
  "description": "Користувач завершив оформлення замовлення",
  "rules": {
    "required": ["order_id", "total", "currency"],
    "properties": {
      "order_id": { "type": "string" },
      "total": { "type": "number", "minimum": 0 },
      "currency": { "type": "string", "enum": ["RUB", "USD", "EUR"] },
      "products": {
        "type": "array",
        "items": {
          "required": ["product_id", "price"],
          "properties": {
            "product_id": { "type": "string" },
            "price": { "type": "number" }
          }
        }
      }
    }
  }
}

Це особливо цінно в командах: розробник не може випадково відправити total: "14500" (рядок замість числа) — Protocols відхилить подію та сповістить.

Functions (Destination Functions)

Коли потрібного Destination немає в каталозі — пишемо Function на JS прямо в UI:

// Segment Function — відправка в користувацький webhook
async function onTrack(event, settings) {
  if (event.event !== 'Order Completed') return;

  const response = await fetch(settings.webhookUrl, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'X-API-Key': settings.apiKey },
    body: JSON.stringify({
      orderId: event.properties.order_id,
      userId: event.userId,
      revenue: event.properties.total,
      timestamp: event.timestamp,
    }),
  });

  if (!response.ok) {
    throw new Error(`Webhook failed: ${response.status}`);
  }
}

Строки

Базове встановлення Analytics.js з page/track/identify — 1 день. Настройка Destinations (Mixpanel + BigQuery + CRM) — 2–3 дні. Настройка Protocols та валідації схем — 1 день. Server-side джерело + functions — ще 1–2 дні.