API Reference

Parameters

Returns

BodyTracker — A new tracker instance in the idle status, ready to be initialized.

Throws

• TypeError — Thrown synchronously if config.apiKey is missing, empty, or not a string.

Example

import { BodyTracker } from "@bodytracker/sdk"; const tracker = new BodyTracker({  apiKey: "bt_live_7Gm3q...redacted",  environment: "production",  activityTypes: ["standing", "walking", "running"],  smoothing: { enabled: true, windowSize: 5 },}); console.log(tracker.getStatus()); // "idle"

Notes

• Constructing a tracker has no side effects on the page — no camera prompt, no network request — until init() is called.
• Use environment: "sandbox" during development to exercise the full API against synthetic tracking data without a real camera feed.

Returns

Promise<void> — Resolves once the tracker has reached the ready status and startSession() can be called.

Throws

• CameraPermissionDeniedError — Thrown if the user denies the camera permission prompt or the browser blocks getUserMedia.
• ModelLoadError — Thrown if the tracking model fails to download or fails to initialize on the current device.

Example

const tracker = new BodyTracker({ apiKey: "bt_test_2Lp9x...redacted" }); try {  await tracker.init();  console.log(tracker.getStatus()); // "ready"} catch (error) {  console.error("Failed to initialize tracker:", error);}

Notes

• Calling init() more than once on the same instance is safe — subsequent calls resolve immediately once the tracker is ready.
• In environment: "sandbox" mode, init() skips the camera permission prompt entirely and resolves against synthetic data.

Parameters

Returns

Promise<Session> — Resolves with the newly created session once recording has started.

Throws

• TrackerNotReadyError — Thrown if init() has not resolved yet — the tracker must be in the ready status.
• SessionAlreadyActiveError — Thrown if a session is already recording or paused; stop it first.

Example

await tracker.init(); const session = await tracker.startSession({  activity: "running",  label: "Morning run",}); console.log(session.id, session.status); // "recording"

Notes

• If options.activity is omitted, the SDK infers the initial activity from the live camera feed as soon as tracking starts.

Returns

Promise<SessionSummary> — Resolves with the completed session's duration, activity, and average tracking quality.

Throws

• NoActiveSessionError — Thrown if there is no recording or paused session to stop.

Example

const summary = await tracker.stopSession(); console.log(`Tracked ${summary.durationSeconds}s of ${summary.activity}`);console.log(`Average quality: ${summary.averageQuality}`);

Returns

void — No return value; check getStatus() to confirm the tracker is now paused.

Throws

• NoActiveSessionError — Thrown if there is no recording session to pause.

Example

tracker.pauseSession();console.log(tracker.getStatus()); // "paused"

Notes

• Unlike stopSession(), pausing does not produce a SessionSummary — the session is still open.

Returns

void — No return value; check getStatus() to confirm the tracker is tracking again.

Throws

• NoActiveSessionError — Thrown if there is no paused session to resume.

Example

tracker.resumeSession();console.log(tracker.getStatus()); // "tracking"

Returns

TrackerStatus — One of "idle" | "initializing" | "ready" | "tracking" | "paused" | "stopped" | "error".

Example

const status = tracker.getStatus(); if (status === "tracking") {  console.log("Currently recording a session.");}

Returns

ActivitySnapshot — The current activity, its tracking quality, and an ISO 8601 timestamp for when it started.

Example

const snapshot = tracker.getActivity(); console.log(`${snapshot.activity} (${snapshot.quality} quality) since ${snapshot.since}`);

Notes

• Before the first activity is detected, activity defaults to "idle" and quality to "searching".

Parameters

Returns

() => void — A function that, when called, removes this exact handler from this exact event.

Example

const unsubscribe = tracker.on("activityChanged", (event) => {  console.log("Activity changed:", event);}); // Later, when you no longer need updates:unsubscribe();

Notes

• The same handler can be registered for multiple events, and the same event can have multiple handlers — all are called in registration order.

Parameters

Returns

void — No return value. Calling off() with a handler that isn't registered is a safe no-op.

Example

function handleQualityChanged(payload: unknown) {  console.log("Quality changed:", payload);} tracker.on("qualityChanged", handleQualityChanged); // ...later, from anywhere with a reference to the same function:tracker.off("qualityChanged", handleQualityChanged);

Parameters

Returns

Promise<Blob> — Resolves with a Blob you can download via a generated object URL or upload elsewhere.

Throws

• SessionNotFoundError — Thrown if no session with the given sessionId exists for this API key.
• UnsupportedFormatError — Thrown if format is not one of "json", "csv", or "pdf".

Example

const summary = await tracker.stopSession();const blob = await tracker.exportSession(summary.id, "csv"); const url = URL.createObjectURL(blob);const link = document.createElement("a");link.href = url;link.download = `session-${summary.id}.csv`;link.click();URL.revokeObjectURL(url);

Notes

• pdf exports are generated server-side and take noticeably longer to resolve than json or csv.

Returns

void — No return value.

Example

tracker.destroy();console.log(tracker.getStatus()); // "stopped"

Notes

• A destroyed instance cannot be reused — construct a new BodyTracker if you need to track again.
• Always call destroy() when unmounting the component or page that owns the tracker to release the camera. @bodytracker/react's hooks do this for you automatically.