UMM-Pixel-SDK

Browser Pixel SDK for the Unified Measurement Model. Captures events in the browser and sends them to umm-eis through the API gateway (single endpoint).

See IMPLEMENTATION_PLAN.md for the full design.

Install on a site

<script>
  window.carter = window.carter || function(){(carter.q=carter.q||[]).push(arguments)};
  carter('init', 'CRT-XXXX', { endpoint: 'https://m.brand.com' }); // CRT-XXXX = tenant_id (= pixel_id)
</script>
<script async src="https://cdn.example.com/carter.iife.js"></script>

API - carter(command, …)

| Command | Usage | |---|---| | init | carter('init', tenant_id, options) - boot. options.endpoint is the single API gateway URL. | | track | carter('track', 'purchase', { value: 89, currency: 'USD' }) | | identify | carter('identify', { email, phone, customer_id }) - email/phone are SHA-256 hashed in-browser. | | consent | carter('consent', 'granted' \| 'pending' \| 'denied') - explicit override. |

Init options: endpoint (required), debug, session_expiry_days, common_properties, user_properties, auto_detect (default true), url_rules, consent_required (default false).

What it does

• Identity: tenant_id (= pixel id, sent on every event) · durable anonymous_customer_id (1P cookie, for stitching) · per-session session_id.
• Auth: none (Phase 1) - the tenant_id identifies the account. No token/KMS.
• Transport: sendBeacon with fetch keepalive fallback → POST {endpoint}/events.
• Auto-detection: page_view (history) + JSON-LD (Product/Order), GA4 dataLayer, per-tenant URL rules, and data-page-type.
• Consent: TCF v2.2 (__tcfapi) + GPC gate (granted → send, pending → hold, denied → drop).
• Privacy: raw email/phone never leave the page (SHA-256 only).
• Bot filtering: automated browsers are skipped.

Develop

pnpm install
pnpm dev          # vite dev
pnpm typecheck
pnpm test         # vitest
pnpm build        # → dist/ (es, cjs, umd, iife). carter.iife.js is the CDN artifact.
pnpm size         # gzip budget gate (<50 KB)

Example stores: pnpm build, then npx serve example and open the landing page. Two integrations of the same demo shop - example/manual/ (explicit carter('track') calls) and example/auto/ (head snippet + auto-detect). Each page mirrors captured events in an on-page inspector, so they work without a running umm-eis. See example/README.md.

Schema sync

The event shape in src/schema/event.ts is the canonical definition and must stay in sync with the PixelEvent struct in umm-eis (Go). There is no shared schema package - keep both in step (PR checklist + CI contract test).