Getting started

Core concepts

The five primitives that everything in Tapemetric is built on.

Events

An event is a single action captured by the SDK or the HTTP API. Every event carries a type (play_start, heartbeat, purchase, …), a timestamp, identifiers, and a bag of context. Events are immutable once ingested.

See Event schema for the full field list.

Sessions

A session groups events from a single viewing occasion. The SDK creates a session id on first use, persists it in localStorage, and rotates it after 30 minutes of inactivity. Concurrency is computed from distinct active session ids in a 90-second window.

You don’t need to manage session ids yourself — the SDK handles this. If you’re using the HTTP API directly, generate a UUID on the client and re-use it within the same viewing session.

Identity: anonymous vs known

Every viewer has two identifiers:

Anonymous id — generated on first SDK load, persisted across page views. Used for pre-login tracking and de-duplication.
User id — set by you when the viewer logs in, via rd.identify(). Links pre-login activity to the now-known user.

typescript

// Anonymous tracking before login
rd.trackPageView('/browse');
rd.trackPageView('/watch/aashiqana');

// After login
rd.identify('user_12345', { plan: 'svod' });

// On logout — wipes anonymous id, starts fresh
rd.reset();

Content

Every playback event should carry a contentId (a stable, URL-safe slug) plus acontentType of series, film, live, orshort. Optional fields include contentTitle, season, andepisode for TV shows.

Tapemetric rolls up metrics per contentId, so keeping ids stable across deploys is important. If you rename a slug, you effectively create a new piece of content for analytics purposes.

Tenants

Each customer workspace is a tenant. Tenants are fully isolated — there is no cross-tenant query. Your tenant id is derived from the API key (for ingest) or the JWT (for the admin panel), never from the client.

API keys vs JWT

Two auth mechanisms, for two audiences:

API keys authenticate SDK ingest. They’re scoped to the write path only. Safe to embed in client code.
JWT bearer tokens authenticate admin panel users. They grant read access to analytics, key management, and settings. Never embed these in clients.