Migration guide
Step-by-step instructions for crossing each major-version boundary in @bodytracker/sdk. Minor and patch releases are always backwards compatible — only major versions require code changes.
This guide covers breaking changes
Each section below corresponds to a major version bump and lists every breaking change introduced at that boundary, followed by concrete before/after steps. If you're jumping multiple majors (e.g. v1.x straight to v3.0), work through both sections in order.
Upgrading from v1.x to v2.0
Breaking changes in this version
- The onEvent callback field on BodyTrackerConfig has been removed.
- Event handling now goes through on(event, handler) / off(event, handler), which support multiple listeners per event and return an unsubscribe function.
- TrackerEventName is now a closed string union — unrecognized event names are rejected instead of silently no-op'd.
1. Remove onEvent from your config
In v1.x, BodyTrackerConfig accepted a single onEvent callback that received every lifecycle event through one function, and you switched on the payload yourself to figure out what happened. That field no longer exists in v2.0.0 — passing it is simply ignored, so upgrading without migrating means you silently stop receiving events. Construct the tracker without it, then attach listeners separately with on().
import { BodyTracker } from "@bodytracker/sdk"; const tracker = new BodyTracker({ apiKey: "bt_live_9Fk2q...redacted",}); const unsubscribeStarted = tracker.on("trackingStarted", () => { console.log("Tracking started");}); const unsubscribeMovement = tracker.on("movementChanged", (payload) => { console.log("Movement changed", payload);});2. Subscribe to each event you previously handled in the onEvent switch
Rather than one dispatcher function, attach a handler per event name you actually care about. Each event now carries its own specific payload shape instead of a shared discriminated union, so downstream handler code gets simpler and better typed.
tracker.on("trackingStarted", () => setIsTracking(true));tracker.on("trackingStopped", () => setIsTracking(false));tracker.on("error", (payload) => reportError(payload));3. Unsubscribe using the function on() returns, or off()
on() returns an unsubscribe function — call it in cleanup (e.g. a React effect's cleanup, or before destroying the tracker) instead of leaking listeners. You can also unsubscribe explicitly with off(event, handler) if you kept a reference to the original handler.
useEffect(() => { const unsubscribe = tracker.on("movementChanged", handleMovementChange); return () => unsubscribe();}, [tracker]);Upgrading from v2.x to v3.0
Breaking changes in this version
- BodyTrackerConfig's trackedActivities field has been renamed to activityTypes.
- React hooks (useTracking, useSession, useCamera, useActivity, useEvents, useAnalytics) have moved out of @bodytracker/sdk into a new @bodytracker/react package.
- Importing React bindings from @bodytracker/sdk will fail to resolve after upgrading — install @bodytracker/react and update your import paths.
1. Rename trackedActivities to activityTypes
The config field was renamed for clarity — the value shape is unchanged, still an array of ActivityType strings. Search your codebase for trackedActivities and rename it wherever BodyTrackerConfig is constructed.
const tracker = new BodyTracker({ apiKey: "bt_live_9Fk2q...redacted", activityTypes: ["standing", "walking", "running"],});2. Install @bodytracker/react
React hooks and components no longer ship inside the core package. Add the new package alongside @bodytracker/sdk before touching any imports, or your build will start failing the moment you update the SDK version.
npm install @bodytracker/react3. Update your React imports to the new package
Keep BodyTracker and other core exports imported from @bodytracker/sdk, but move every hook import — useTracking, useSession, useCamera, useActivity, useEvents, useAnalytics — over to @bodytracker/react.
import { BodyTracker } from "@bodytracker/sdk";import { useTracking, useSession } from "@bodytracker/react"; function TrackingPanel() { const { status } = useTracking(); const { session } = useSession(); return <div>{status}</div>;}