Embeddable Session Replay configuration

The embed URL drives the Embeddable Session Replay viewer entirely. The path selects what to replay, and a single percent-encoded config JSON object carries authentication plus every render, camera, path, and aggregation setting. To change these settings after load, use the runtime API.

Prerequisites

A user-level JWT and the target session's identifiers. See Embeddable Session Replay for partners.

URL format

The scene format targets one scene, and the project format spans scene visits across a project:

https://replay.cognitive3d.com/scene/{sceneId}?apiTokenMode=true&projectId={projectId}&version={version}&sessionIds={json}&sessionId={numeric}&config={json}

https://replay.cognitive3d.com/project/{projectId}?apiTokenMode=true&sessionIds={json}&config={json}

Three rules apply to every URL:

sessionIds and config are JSON. Always run them through encodeURIComponent rather than hand-substituting %7B and %22.
apiKey is not a top-level query parameter. It lives inside config.
Query keys are case-sensitive exactly as written below.

Top-level query parameters

Field	Type	Default	Definition
`projectId`	numeric string	`-1` (falls back to the scene's project)	Numeric Cognitive3D project ID. Required in the scene format. In the project format it comes from the path instead.
`version`	integer string	`-1`	Scene version number, the human-facing `v17`. Ignored in project mode, where visits carry their own versions.
`versionId`	integer string	`-1`	Internal scene version ID, a database ID rather than the version number. Scene Viewer links use this. When present it wins over the session's own version.
`sceneId`	UUID string	from path	Overrides the scene UUID taken from `/scene/{sceneId}`.
`sessionIds`	URL-encoded JSON array of strings	`[]`	Internal session hash IDs to load, for example `["1775515259_5b5bf774..."]`. Multiple IDs load a multi-session replay. The viewer removes duplicates and loads the first 10 IDs. Read once at page load. Later selection changes rewrite the URL but do not re-seed from it.
`selectedSessionId`	string	none	The viewer writes this when more than one session is active, so a shared link reopens with the same session focused. Removed automatically when only one session is active.
`sessionId`	numeric string	`-1`	Numeric session ID used to deep-link the player for audio, transcript, and project-visit lookups. Not consumed in project mode.
`config`	URL-encoded JSON object	`{}`	The viewer configuration override, deep-merged over the app defaults. Carries `apiKey` and every setting below. Invalid JSON is ignored with a console warning.
`apiTokenMode`	`true` or `false`	`false`	Token-authenticated embed mode. The Embed Configurator always sets `true`. In this mode the viewer skips the CSRF and cookie login path, gates rendering on a token being present, and asks the parent for one with `tokenRequired` when the URL carries none.
`mode`	`sessionReplay`, `sceneViewer`, `objectExplorer`, or `appWidget`	`sessionReplay`, or `sceneViewer` on `/viewer/model`	Viewer mode. Each mode picks its own default camera control and aggregation type.
`debug`	`true` or `false`	`false`	Enables the Tweakpane debug UI.

The config object

The config object is deep-merged over the viewer's defaults, so include only what you want to change. The Embed Configurator omits every field that already matches the default.

Field	Type	Default	Definition
`apiKey`	string	`""`	The credential the viewer authenticates with: a user-level embed JWT sent as the `c3d-sr-embed-token` header, or an organization API key sent as `Authorization`. A JWT scopes access by its `sceneIds`, `versionIds`, and `projectId` claims, and anything outside those claims is refused.
`controlType`	string	`orbit` in Session Replay, Scene Viewer, and Object Explorer, `topdown` in the app widget	Camera control type. See Camera control types.
`verticalSliceAmount`	number 0 to 1	`1`	Elevation clip. `1` shows the whole scene. Lower values clip geometry above a Y plane so you can see into a building from above.
`cameraSensitivity`	number 0.1 to 20, in meters per second	`10`	How far keyboard moves, pans, and zooms go. In Fly Through (`fly`) it is the movement speed. Labeled Camera Sensitivity in the Embed Configurator and in the viewer. The original name, `cameraSpeed`, is still read when `cameraSensitivity` is absent.
`initialCamera`	`{ position, target, fovDeg, orthoHeight }`	`undefined`	The opening view, in place of the viewer's own scene framing. Uses the same pose shape as the camera API, so a pose read with `get` opens the embed on that saved view. The viewer applies it once the scene has loaded, and again when a later config carries a different pose or a different `controlType`. Each camera control type takes only the fields it does not place itself. See Initial camera.
`renderConfig`	object	see below	Render and UI toggles.
`pointCloudConfig`	object	see below	Cube point-cloud aggregation appearance.
`heatmapConfig`	object	see below	Aggregated heatmap appearance.
`slicerQueryData`	object	`undefined`	Pre-computed aggregation payload, `{ main: { bin_size, session_count, counts[] } }`, injected directly instead of querying the API.
`sceneConfig`	object	see below	`scale`, `sceneName`, `sdkVersion`, `cameraPos`, and `cameraRot`. The viewer mostly writes these back.

Camera control types

controlType sets how the camera moves and what it follows. The Embed Configurator labels each type under Camera Controls.

Value	Embed Configurator label	Behavior
`orbit`	Orbit Scene	Orbits a point in the scene. In Session Replay it opens on the participant's HMD. This is the viewer default when `controlType` is absent.
`fly`	Fly Through	Flies freely through the scene. Click to capture the mouse, then look with the mouse and move with WASD, Space, and Shift.
`firstPerson`	First Person	Rides the participant's HMD.
`followCamera`	Follow Camera	Holds a position near the participant and turns to keep them in view, moving only when they walk away, come too close, or are hidden behind geometry. The Embed Configurator selects this by default.
`topDown`	Top Down	Overhead view with an orthographic camera that centers on the participant.
`topdown`	none	Fixed overhead view framed on the scene. The app widget default.

Values are case-sensitive: topdown and topDown behave differently. Older names still work: fps runs fly, followUser and the retired thirdPerson run followCamera, and the retired freeLook runs orbit.

Initial camera

initialCamera takes a pose, and each camera control type uses only the fields it does not place itself:

Camera control type	Fields used
`orbit` and `fly`	`position`, `target`, and `fovDeg`
`topdown`	`target` and `orthoHeight`
`topDown`	`orthoHeight` only, because the view centers on the participant
`firstPerson` and `followCamera`	none, because the participant's HMD places the camera

position and target are [x, y, z] positions in the viewer's world space. Leave out fovDeg and orthoHeight to keep the mode's own zoom. The Embed Configurator's Camera section builds this object from its Position and Target fields, and its FOV and Top-down height fields appear only while the preview's zoom differs from the mode's own.

Render configuration

renderConfig controls what the viewer draws and which parts of its own UI appear.

Field	Type	Default	Definition
`ui`	boolean	`true`	Show the player UI: timeline, header, and settings. Set `false` for a bare canvas.
`autoplay`	boolean	`false`	Start playback on load. With audio present, the browser may require a consent click first. Project mode defers autoplay to the audio path.
`loopSession`	boolean	`true`	Restart from the beginning when the timeline ends.
`darkMode`	boolean	`false`	Dark background for the 3D scene itself.
`darkModeForWidgets`	boolean	`false`	Dark theme for the surrounding UI chrome. Sets `data-theme` on the document.
`gridEnabled`	boolean	`false`	Floor grid.
`axesHelperEnabled`	boolean	`false`	Debug XYZ axes at the origin.
`boundingBoxEnabled`	boolean	`false`, `true` in Object Explorer	Debug bounding boxes around scene geometry and Dynamic Objects.
`boundaryEnabled`	boolean	`true`	VR play space boundary polygon.
`legendEnabled`	boolean	`true`	Color-map legend for the active aggregation display.
`eventToastEnabled`	boolean	`false`	Toast popups when session events fire during playback.
`controllerModalEnabled`	boolean	`true`	Controller-button overlay showing which inputs are pressed.
`avatarHeadEnabled`	boolean	`true`	Participant avatar head at the HMD position.
`namePlatesEnabled`	boolean	`true`	Each participant's name above their head. Labeled Nameplates in the Embed Configurator.
`lightIntensity`	number 0 to 100	`80`	Scene lighting intensity, in percent. Labeled Lighting Intensity in the Embed Configurator.
`fullscreenButtonEnabled`	boolean	`false` in Session Replay, `true` in other modes	Floating fullscreen button, for embeds running with `ui: false`.
`fullscreen`	boolean	`false`	Enter or exit fullscreen. Intended to be toggled at runtime with `postMessage`.
`sceneVersionEnabled`	boolean	`true`	Show the Scene Version label.
`pathVisible`	boolean	`false`	Master toggle for the movement path overlay. `pathType` and `pathSize` do nothing while this is `false`.
`pathType`	`head` or `floor`	`head`	Draw the HMD trajectory or its floor projection.
`pathSize`	number 0 to 1	`0.1`	Path line weight. The configurator's slider shows a percentage and stores the value divided by 100.
`cloudPointsEnabled`	boolean	`true`	Render the cube point-cloud aggregation.
`cloudPointsSize`	number 0 to 10	`1` in Scene Viewer and the app widget, `25` in Session Replay and Object Explorer	Point-cloud cube size.
`pointsAlwaysOnTop`	boolean	`false`	Draw aggregation points over scene geometry. The app widget uses this.
`heatmapEnabled`	boolean	`false`	Render the aggregated heatmap volume instead of cubes.
`ssaoEnabled`	boolean	`true`	Screen-space ambient occlusion post-process, labeled Ambient Occlusion in the UI.
`ssaoRadius` and `ssaoStrength`	number	`0.1` and `0.5`	SSAO sampling radius in view-space units, and darkening strength.
`sobelEnabled` and `sobelIntensity`	boolean and number	`false` and `1.0`	Sobel edge-darkening post-process and its multiplier.
`sceneVisible`	boolean	`true`	Hide the scene mesh while keeping session data visible.
`distanceCulling`	`{ enabled, maxDistance }`	`{ true, 300 }`	Skip geometry beyond `maxDistance` meters from the camera.
`maxFPS`	number	`120`	Frame-rate cap.
`resolutionFactor`	number	`1`	Render-scale multiplier. Below `1` trades sharpness for performance.
`sliceClipY`	number	computed	Absolute Y clip plane derived from `verticalSliceAmount`. Set the percentage instead.
`runQueryTimestamp`	number	`undefined`	Bump to a fresh `Date.now()` to force the aggregation query to re-run on the next config update.

Point cloud and heatmap appearance

pointCloudConfig and heatmapConfig share the same shape. Two fields apply to the point cloud only.

Field	Type	Default	Definition
`colorMap`	`default`, `inferno`, `jet`, `plasma`, `viridis`, `magma`, `cividis`, or `turbo`	`default`	Color palette used for density.
`normalizationMethod`	`minmax`, `percentile`, `logPercentile`, `log`, or `cdf`	`minmax`	How raw counts map into the 0 to 1 color range. The percentile modes are the ones that read `percentileParams`.
`gammaCorrection`	number 0 to 1	`0.55`	Intensity gamma. Higher values brighten low-density areas.
`percentileParams.min` and `.max`	number 0 to 1	`min` is `0.01` for the point cloud and `0` for the heatmap. `max` is `0.99` in Scene Viewer and `0.95` in other modes.	Lower and upper percentile clamps applied before normalization.
`defaultPointSize`	number	`1` in Session Replay, `2` in Scene Viewer, `10` in the app widget	Minimum point size used as the normalization floor.
`blendMode`	`1` blend, `2` additive, or `3` opaque	`1`	Point-cloud blending. Point cloud only.
`tint`	`[r, g, b]`	`[1, 1, 1]`	Color multiplier. Point cloud only.
`active` and `enabled`	boolean	`active` is `true` except in Object Explorer. `enabled` is `false`.	Whether the point cloud or heatmap subsystem is live.

Configuration example

This configuration hides the UI, starts playback on load, follows the participant, and draws the head path at 25 percent weight. It carries no apiKey, because the parent page delivers the user-level JWT over postMessage:

{
  "controlType": "followCamera",
  "renderConfig": {
    "ui": false,
    "autoplay": true,
    "pathVisible": true,
    "pathType": "head",
    "pathSize": 0.25
  }
}