WebView messages (Tracking endpoint)

Message types emitted by /pose_tracker/tracking and when they fire.

The Tracking endpoint emits structured messages during real-time tracking.

Use them to drive UI and business logic.

How messages are delivered

In a browser iframe, messages are sent via window.postMessage.

In mobile apps, they go through the WebView bridge.

Some integrations stringify the payload.

Handle both cases:

• event.data is an object

• event.data is a JSON string

Typical V3 flow (real-time)

1. initialization messages while the model and camera load.

2. posture messages until placement is good.

3. Optional placement countdown (still posture messages).

4. counter starts once tracking is active.

5. Optional advanced outputs, depending on flags:

   • form_score

   • progression

   • recommendations

   • keypoints

   • angles

6. Jump flows (when using jump_analysis / air_time_jump):

   • jump_calibration → jump_started → jump_height

   • optional jump_discarded

Message types (Tracking)

initialization (realtime)

Sent while the page loads and initializes.

Fields:

• type (string) — always "initialization".

• message (string) — human-readable status.

• ready (boolean) — true only when tracking can start.

Example:

{
  "type": "initialization",
  "message": "Loading pose model",
  "ready": false
}

error (realtime)

Sent when the configuration or runtime fails.

Fields:

• type (string) — always "error".

• code (string) — machine-readable error code.

• message (string) — human-readable description.

• details (object, optional) — extra debug info.

Example:

{
  "type": "error",
  "code": "invalid_exercise",
  "message": "Unknown exercise: split",
  "details": {
    "exercise": "split"
  }
}

Common codes you should handle:

• missing_token — token is missing.

• invalid_token — token is invalid or revoked.

• invalid_exercise — exercise is missing or unknown.

• developer_features_not_allowed — plan-gated flag used on Free plan.

• webgl_unavailable — poseBackend=webgl requested but not available.

• wasm_unavailable — poseBackend=wasm requested but cannot load.

• camera_permission_denied — user denied camera access.

• camera_not_found — no camera available.

• jump_analysis_missing_height — userHeightCm required for jump_analysis.

posture (realtime placement)

Sent continuously during placement.

It tells you what the user should do to be “ready”.

Fields:

• type (string) — "posture".

• message (string) — guidance text for the user.

• direction (string) — placement direction hint. Example: "in-frame".

• ready (boolean) — true when tracking can start.

• requirements (array, optional) — unmet requirements.

• countdownSecondsLeft (number, optional) — present when countdown is enabled.

Example:

{
  "type": "posture",
  "message": "Step back. Keep your full body in frame.",
  "direction": "in-frame",
  "ready": false,
  "requirements": ["full_body_visible"],
  "countdownSecondsLeft": 0
}

counter (realtime)

Sent when exercise tracking is active.

For repetition exercises, it increments on each validated rep.

For duration exercises, it increments over time (seconds).

Fields:

• type (string) — "counter".

• current_count (number) — reps or seconds.

• exercise (string, optional) — movement key.

Example:

{
  "type": "counter",
  "exercise": "squat",
  "current_count": 6
}

form_score (realtime, optional)

Sent when form scoring is enabled for the exercise.

This is a compact “how good is the current posture” signal.

Fields:

• type (string) — "form_score".

• score (number) — 0 to 100.

• label (string, optional) — example: "good", "needs_work".

Example:

{
  "type": "form_score",
  "score": 82,
  "label": "good"
}

recommendations (realtime, plan-gated)

Sent when recommendations=true.

Fields:

• type (string) — "recommendations".

• data (array<string>) — feedback strings, ordered by priority.

Example:

{
  "type": "recommendations",
  "data": [
    "Keep your knees aligned with your toes.",
    "Lower your hips a bit more."
  ]
}

progression (realtime, plan-gated)

Sent when progression=true.

This is usually a rep-phase progress signal.

Fields:

• type (string) — "progression".

• value (number) — 0 to 100.

Example:

{
  "type": "progression",
  "value": 47
}

keypoints (realtime, plan-gated)

Sent when keypoints=true.

Fields:

• type (string) — "keypoints".

• data (array<object>) — keypoints.

Keypoint object:

• name (string) — landmark name.

• x (number) — pixels.

• y (number) — pixels.

• score (number) — confidence 0 → 1.

Example:

{
  "type": "keypoints",
  "data": [
    { "name": "nose", "x": 322.3, "y": 78.1, "score": 0.99 },
    { "name": "left_shoulder", "x": 366.4, "y": 132.7, "score": 0.98 }
  ]
}

angles (realtime, plan-gated)

Sent when angles=true.

Fields:

• type (string) — "angles".

• data (object) — computed angles.

Example:

{
  "type": "angles",
  "data": {
    "left_side": {
      "knee_angle": { "from_hip_to_ankle": 164 }
    },
    "right_side": {
      "knee_angle": { "from_hip_to_ankle": 168 }
    }
  }
}

Jump messages (realtime, custom exercises)

These fire only for:

• exercise=jump_analysis

• exercise=air_time_jump

jump_calibration (jump_analysis only)

Sent during calibration.

{
  "type": "jump_calibration",
  "ready": false,
  "message": "Hold still"
}

jump_started

Sent once per detected jump.

{
  "type": "jump_started"
}

jump_discarded

Sent when a jump attempt is detected but rejected.

Typical reasons are missing hips, occlusion, or unstable baseline.

{
  "type": "jump_discarded",
  "reason": "hips_not_visible"
}

jump_height

Sent during measurement and/or when a jump completes.

Payload differs slightly by jump type.

{
  "type": "jump_height",
  "jumpHeightCm": 31.8,
  "final": true
}

jump_summary

Sent for upload-video analyses.

It is not typically emitted in real-time mode.

Related

• Query params: Query parameters (Tracking endpoint)

• Upload messages: WebView / native messages