@unitrack/web

UniTrack web SDK — auto-capture screen + tap + network + crash, offline queue, W3C trace context, fan-out tới Snowplow / HTTP custom.

API parity với Flutter / iOS / Android version.

Install

npm install @unitrack/web

Hoặc <script> IIFE:

<script src="https://unpkg.com/@unitrack/web/dist/unitrack.iife.js"></script>

Quick start

import UniTrack, { SnowplowProvider } from '@unitrack/web';

UniTrack.initialize('utk_your_api_key', {
  endpoint: 'https://your-ingest.example.com/events',
  autoCapture: true,
  trackTaps: true,
  trackScreens: true,
  trackNetwork: true,
  piiSalt: 'your_pii_salt_hex',
  tracingAllowlistHosts: ['api.yourapp.com', '*.yourcompany.com'],
});

// Optional Snowplow
UniTrack.addProvider(new SnowplowProvider({
  endpoint:   'https://collector.yourapp.com',
  appId:      'web_app',
  igluVendor: 'com.yourcompany.tracker',
}));

// Identify sau khi user login
await UniTrack.identify(userEmail, { plan: 'pro' });

// Custom event
UniTrack.customTrack('purchase_completed', {
  action: 'completed',
  data: { order_id: 'A-1024', amount: 99000 },
  includeUser: true,
});

Demo

npm run build
python3 -m http.server 8000  # hoặc bất kỳ static server
# Mở http://localhost:8000/demo/

API

| Method | Mô tả | |---|---| | initialize(apiKey, config?) | Init 1 lần ở app bootstrap | | track(name, props?) | Manual track event | | customTrack(name, { action, data, includeUser }) | Custom event với stamp event_action + optional user_id | | identify(userId, traits?) | Hash PII trước khi cache (nếu piiSalt set) | | reset() | Clear identity, logout flow | | setScreen(name) | Override screen name | | currentSessionId() / sessionIndex() / previousSessionId() | Session getter | | rotateSession() | Force rotate (logout / switch-account) | | addProvider(p) | Register provider (Snowplow, HttpProvider, ...) | | flush() | Force flush mọi provider |

Auto-capture

Cờ trong initialize(config):

| Cờ | Event tự bắt | |---|---| | trackTaps: true | click — document-level capture, resolve element_key qua data-track-id > id > aria-label > text | | trackScreens: true | screen_viewed + screen_load_completed — hook pushState/replaceState + popstate + hashchange | | trackNetwork: true | network_request / network_error — patch fetch + XMLHttpRequest |

App có thể override tên event qua screenStartEvent, screenLoadEvent, clickEvent config.

W3C Trace Context

tracingAllowlistHosts: ['api.yourapp.com', '*.yourcompany.com']

→ SDK tự inject header traceparent: 00-<trace>-<span>-01 vào fetch/XHR đi tới host trong list. Fail-closed: empty list = không inject. BE phải Access-Control-Allow-Headers: traceparent mới nhận được CORS.

Offline queue

IndexedDB — event lưu khi navigator.onLine === false, tự flush khi online event fire. Fallback: navigator.sendBeacon khi page unload.

PII hash

SHA-256(salt + raw) qua crypto.subtle. Cache in-memory để tránh re-hash. Salt rotate → cache tự invalidate.