Tracker SDK

This SDK captures web events in-browser and sends them to POST /api/v1/collect.

Integration goals

• one-line HTML bootstrap
• auto-tracking enabled by default
• canonical payload normalization before send
• compatibility with runtime analytics.init(...) overrides

Initialization

Projects can initialize tracking with a single HTML line:

<script src="/sdk/tracker.js?api_key=trk_live_xxx"></script>

Auto-tracking is enabled by default for this bootstrap style.

Optional query params:

• auto=0: disable auto-tracking at bootstrap

The SDK still supports existing globals for compatibility:

• window.__TRACKER_KEY__
• window.__TRACKER_API_KEY__
• window.__TRACKER_AUTO__
• window.__TRACKER_PID__ (optional)

Runtime configuration is also supported:

import "../sdk/tracker.js";

window.analytics.init({
  apiKey: "trk_live_xxx",
  autoTrack: true, // optional
  debug: false // optional
});

SDK endpoint is intentionally fixed to same-origin /track and cannot be overridden from browser code.

projectId is optional in SDK config and is not required for normal usage. Backend resolves project using the API key.

analytics.init(...) validates the API key against the backend before activating tracking. It returns a promise that resolves after validation succeeds and rejects with status === 401 when the API key is missing or status === 403 when the key has been revoked.

Public API

• analytics.init(config)
• analytics.autotrack(overrides)
• analytics.track(event, properties)
• analytics.identify(userId, traits)
• analytics.purchase(payload)
• analytics.getConfig()

npm Package Usage

Install from npm:

npm install @jsv10/tracker-sdk

Or install from GitHub Packages:

npm install @jsv10/tracker-sdk --registry=https://npm.pkg.github.com

Then import and initialize:

import "@jsv10/tracker-sdk";

window.analytics.init({
  apiKey: import.meta.env.VITE_TRACKER_API_KEY,
  autoTrack: true,
});

CDN / HTML Usage

Script-tag query params still work for bootstrapping (api key and auto mode):

<script src="https://unpkg.com/@jsv10/tracker-sdk@latest/dist/tracker.min.js?api_key=trk_live_xxx&auto=0"></script>

Data Sent By SDK

Each event payload includes:

• event_name
• timestamp (ISO string)
• api_key
• session_id
• user_id (defaults to anonymous id until identify is called)
• anonymous_id
• page_url
• referrer
• user_agent
• source, medium, campaign
• device_type, platform, is_new_user
• event-specific fields (duration, traits, value, order_id, product_id, category, cart_value, quantity, etc.)
• event_properties (custom metadata + detector payload)
• optional project_id if configured manually

For analytics.purchase(payload), required fields are:

• order_id
• value (or legacy revenue)
• currency (3-letter code, for example USD)
• product_id
• category
• quantity (> 0)
• cart_value

If any required purchase field is missing or invalid, the backend rejects the event with 400.

Currency behavior:

• 3-letter uppercase format is required by backend validation.
• Lowercase inputs are normalized server-side (for example usd -> USD).

Idempotency behavior:

• use a stable order_id per order attempt
• retries with the same order_id are deduplicated server-side

Dynamic Auto-Tracking

When autoTrack is enabled, SDK dynamically inspects runtime interactions.

Canonical auto events

• product_view
• view_product (emitted as an alias with the same detector payload)
• add_to_cart
• begin_checkout
• purchase_intent
• search
• signup
• login
• remove_from_cart
• click_cta
• click (emitted only for key CTAs, not every link click)

Core lifecycle + commerce events

• pageview
• page_view (emitted as an alias with the same payload)
• session_start
• session_end
• purchase

Keywords used for classification

• add_to_cart: add to cart, add-to-cart, add cart, add bag, add basket
• begin_checkout: checkout, proceed to checkout, go to checkout
• purchase_intent: buy now, purchase, order now, pay now, get now
• search: search, find, look for, query
• signup: sign up, signup, register, create account, join now
• login: log in, login, sign in, signin, continue with, my account
• remove_from_cart: remove, remove from cart, delete item, remove item
• click_cta: learn more, shop now, view details, explore, start now, get started, see plans

Detector metadata

Auto events attach detector metadata in event_properties.detector:

{
  "event_name": "add_to_cart",
  "timestamp": "2026-04-10T12:00:00Z",
  "api_key": "trk_live_xxx",
  "session_id": "uuid",
  "anonymous_id": "anon_123",
  "page_url": "/store",
  "event_properties": {
    "detector": {
      "kind": "click",
      "confidence": 0.95,
      "matched_keywords": ["add to cart"],
      "selector": "button.add-btn",
      "tag": "button",
      "label": "Add to Cart"
    }
  }
}

Session behavior

• Creates session id in localStorage (trk_sid)
• Creates anonymous id in localStorage (trk_aid)
• Refreshes session activity from user interactions
• Sends session_start when session expires/new
• Sends session_end when a previous session times out and a new one starts
• Sends pageview on initial load and SPA route changes
• Emits alias events (page_view, view_product, click) alongside their canonical event names
• Sends time_on_page on visibility hidden / unload

Hosting patterns

1. Local/self-hosted: <script src="/sdk/tracker.js?api_key=..."></script>
2. npm-backed CDN script: https://cdn.jsdelivr.net/npm/@jinishv28/tracker-sdk@<version>/dist/tracker.min.js
3. npm package distribution: install @jsv10/tracker-sdk and import in app build step