SDK Reference
A conceptual tour of the @bodytracker/sdk core: how the tracker initializes, how it's configured, how it moves through its lifecycle, and the constants and types that make up its public surface. For the method-by-method breakdown, see the API Reference.
Initialization
Creating a tracker is deliberately split into two steps. The new BodyTracker(config) constructor is synchronous and cheap — it validates your config and returns an instance in the idle status, with no side effects on the page. Nothing touches the camera or downloads a model yet, so you can construct a tracker eagerly (at module scope, in a provider, wherever is convenient) without worrying about triggering a permission prompt or a network request too early.
init() is where the real work happens: it requests camera access via getUserMedia, downloads and warms up the on-device tracking model, and only then transitions the tracker to ready. Separating the two steps means you control exactly when the permission prompt appears — for example, behind a user-initiated "Enable camera" button, rather than the moment your component mounts.
import { BodyTracker } from "@bodytracker/sdk"; // 1. Construct — synchronous, cheap, no camera or model work yet.const tracker = new BodyTracker({ apiKey: "bt_live_4Nq8v...redacted" }); // 2. Initialize — async, requests camera permission and loads the model.await tracker.init(); console.log(tracker.getStatus()); // "ready"Configuration
Every option accepted by the BodyTrackerConfig object passed to the constructor:
| Parameter | Type | Description |
|---|---|---|
apiKeyRequired | string | Your BodyTracker API key, e.g. "bt_live_..." for production or "bt_test_..." for sandbox testing. |
environmentOptional | "production" | "sandbox" | Use "sandbox" during development to exercise the API against synthetic tracking data with no camera required. Default: "production" |
cameraDeviceIdOptional | string | The deviceId of a specific camera to use. Omit to let the SDK pick the system default. |
activityTypesOptional | ActivityType[] | Restricts detection to a subset of activity types. Omit to detect all supported activities. |
smoothingOptional | { enabled: boolean; windowSize?: number } | Applies a rolling-average filter to reduce jitter in movement data. windowSize is the number of frames averaged. |
localeOptional | string | A BCP 47 locale tag (e.g. "en-US") used to localize error messages and export labels. |
Lifecycle
A tracker instance moves through a small, well-defined state machine. Read the current state at any point with getStatus(), or subscribe to lifecycle and tracking events for reactive updates instead of polling.
idle— immediately after construction. Nothing has happened yet.initializing— whileinit()is in flight.ready— init() resolved; waiting for a session.tracking⇄paused— a session is active; pauseSession()/resumeSession() move back and forth between these two without ending it.stopped— afterdestroy(). Terminal — construct a new tracker to track again.
error is reachable from any state
A tracker can transition to error from any other state if initialization fails or an unrecoverable runtime error occurs — always attach an error listener in production.
Utilities
Beyond the core lifecycle and session methods, the tracker exposes exportSession() for turning a completed session into a downloadable json, csv, or pdf export — see the API Reference entry for its full signature, parameters, and an example.
Constants
TrackerStatus
| Value | Meaning |
|---|---|
"idle" | The tracker has been constructed but init() has not been called yet. |
"initializing" | init() is in progress — requesting camera permission and loading the tracking model. |
"ready" | init() has resolved; the tracker is ready to start a session. |
"tracking" | A session is actively recording movement data. |
"paused" | A session exists but is paused via pauseSession(). |
"stopped" | destroy() has been called; the instance can no longer be used. |
"error" | An unrecoverable error occurred during initialization or tracking. |
ActivityType
| Value | Meaning |
|---|---|
"standing" | Subject is upright and stationary. |
"walking" | Subject is moving at a walking pace. |
"running" | Subject is moving at a running pace. |
"sitting" | Subject is seated. |
"idle" | No activity has been confidently detected yet. |
QualityLevel
| Value | Meaning |
|---|---|
"excellent" | High-confidence tracking with a clear, well-lit view of the subject. |
"good" | Reliable tracking with minor visibility or lighting limitations. |
"limited" | Tracking is degraded — consider repositioning the camera or subject. |
"searching" | The tracker is actively trying to reacquire the subject. |
"offline" | No camera feed is available to evaluate quality. |
Types & Interfaces
The full set of TypeScript declarations that make up the core SDK's public surface, exported from @bodytracker/sdk:
1class BodyTracker {2 constructor(config: BodyTrackerConfig);3 init(): Promise<void>;4 startSession(options?: StartSessionOptions): Promise<Session>;5 stopSession(): Promise<SessionSummary>;6 pauseSession(): void;7 resumeSession(): void;8 getStatus(): TrackerStatus;9 getActivity(): ActivitySnapshot;10 on(event: TrackerEventName, handler: (payload: unknown) => void): () => void; // returns unsubscribe fn11 off(event: TrackerEventName, handler: (payload: unknown) => void): void;12 exportSession(sessionId: string, format: "json" | "csv" | "pdf"): Promise<Blob>;13 destroy(): void;14}15 16interface BodyTrackerConfig {17 apiKey: string;18 environment?: "production" | "sandbox"; // default "production"19 cameraDeviceId?: string;20 activityTypes?: ActivityType[];21 smoothing?: { enabled: boolean; windowSize?: number };22 locale?: string;23}24 25interface StartSessionOptions {26 activity?: ActivityType;27 label?: string;28}29 30type TrackerStatus =31 | "idle"32 | "initializing"33 | "ready"34 | "tracking"35 | "paused"36 | "stopped"37 | "error";38 39type ActivityType = "standing" | "walking" | "running" | "sitting" | "idle";40 41type QualityLevel = "excellent" | "good" | "limited" | "searching" | "offline";42 43interface Session {44 id: string;45 startedAt: string;46 activity: ActivityType;47 status: "recording" | "paused";48}49 50interface SessionSummary {51 id: string;52 durationSeconds: number;53 activity: ActivityType;54 averageQuality: QualityLevel;55}56 57interface ActivitySnapshot {58 activity: ActivityType;59 quality: QualityLevel;60 since: string;61}62 63type TrackerEventName =64 | "ready"65 | "trackingStarted"66 | "trackingStopped"67 | "trackingLost"68 | "trackingRestored"69 | "sessionStarted"70 | "sessionEnded"71 | "movementChanged"72 | "activityChanged"73 | "qualityChanged"74 | "error";