Events

Fires once, after init() completes successfully and the tracker's status becomes ready. Equivalent to awaiting init(), but useful when init() is called somewhere you don't control, e.g. inside a provider.

tracker.on("ready", ({ timestamp }) => {  console.log(`Tracker ready at ${timestamp}`);}); await tracker.init();

Fires when frame-by-frame movement tracking actually begins for a session — after startSession() resolves and the first camera frame has been processed. Distinct from sessionStarted, which fires immediately when the session is created.

tracker.on("trackingStarted", ({ sessionId, activity }) => {  console.log(`Tracking ${activity} for session ${sessionId}`);});

Fires whenever the tracker stops processing camera frames for the active session — including pauseSession(), stopSession(), and the tracker losing the subject unexpectedly.

tracker.on("trackingStopped", ({ sessionId, reason }) => {  console.log(`Session ${sessionId} stopped tracking: ${reason}`);});

Fires mid-session when the tracker can no longer confidently detect the subject — poor lighting, the subject leaving the frame, or camera obstruction. The session stays active; tracking resumes automatically once conditions improve, firing trackingRestored.

tracker.on("trackingLost", ({ reason, since }) => {  showBanner(`Lost tracking (${reason}) at ${since}`);});

Fires after a trackingLost event once the tracker successfully re-detects the subject and resumes producing movement data for the active session.

tracker.on("trackingRestored", ({ downtimeMs }) => {  hideBanner();  console.log(`Tracking restored after ${downtimeMs}ms`);});

Fires whenever the subject transitions between moving and stationary, independent of which specific activity is detected. Fires far more frequently than activityChanged and is best suited to lightweight UI like a "live" indicator rather than analytics.

tracker.on("movementChanged", ({ isMoving }) => {  liveIndicator.classList.toggle("active", isMoving);});

Fires whenever the tracker's detected activity type changes for the active session, e.g. walking to running. The most commonly used tracking event for driving activity-aware UI.

tracker.on("activityChanged", ({ from, to, timestamp }) => {  console.log(`${from} -> ${to} at ${timestamp}`);});

Fires whenever the tracker's confidence in its own readings changes — driven by lighting, camera angle, and subject distance. Use it to prompt users to reposition when quality drops to "limited" or "searching".

tracker.on("qualityChanged", ({ to }) => {  if (to === "limited" || to === "searching") {    showRepositionHint();  }});

Fires immediately when startSession() creates a new session, with the same Session object startSession()'s promise resolves with. Useful for reacting to session creation from a listener registered elsewhere in the app, without awaiting the call yourself.

tracker.on("sessionStarted", (session) => {  console.log("Session started:", session.id, session.activity);});

Fires when stopSession() finalizes a session, with the same SessionSummary its promise resolves with. Good place to trigger persistence or analytics without threading the summary through the call site.

tracker.on("sessionEnded", (summary) => {  saveSessionToServer(summary);});

Fires whenever the tracker encounters a runtime error outside a specific method call's promise — e.g. the camera device is unplugged mid-session. Always keep an error listener attached in production; unhandled tracker errors otherwise fail silently.

tracker.on("error", ({ message, code, recoverable }) => {  console.error(`[${code}] ${message}`);  if (!recoverable) {    tracker.destroy();  }});