> For the complete documentation index, see [llms.txt](https://docs.multiset.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.multiset.ai/webxr-sdk/api-reference/xrsessionmanager.md).

# XRSessionManager

```typescript
import { XRSessionManager } from '@multisetai/vps/core';
```

Manages the full WebXR session: starts and stops the immersive-ar session, runs the frame loop, captures camera frames, and calls the Multiset API. Use this directly when building a custom renderer. When using Three.js or Needle Engine, the adapter creates and owns this internally.

### Constructor

```typescript
new XRSessionManager(gl: WebGL2RenderingContext, options: IXRSessionOptions)
```

### Session Options

| Parameter                | Type                       | Default                | Description                                                                       |
| ------------------------ | -------------------------- | ---------------------- | --------------------------------------------------------------------------------- |
| `client`                 | `MultisetClient`           | Required               | Authorized HTTP client                                                            |
| `overlayRoot`            | `HTMLElement`              | —                      | Root element for WebXR DOM overlay                                                |
| `autoLocalize`           | `boolean`                  | —                      | Start localization automatically when the session begins                          |
| `relocalization`         | `boolean`                  | —                      | Re-localize when AR tracking loss is recovered                                    |
| `confidenceCheck`        | `boolean`                  | —                      | Reject results below `confidenceThreshold`                                        |
| `confidenceThreshold`    | `number`                   | `0.5`                  | Minimum accepted confidence (0.2 to 0.8)                                          |
| `poseTimeoutMs`          | `number`                   | `10000`                | Max milliseconds to wait for a viewer pose before aborting                        |
| `backgroundLocalization` | `boolean`                  | —                      | Re-localize on an interval during the session                                     |
| `bgLocalizationInterval` | `number`                   | `30` (VPS) / `10` (OT) | Seconds between background localization attempts (10 to 180)                      |
| `autoTracking`           | `boolean`                  | —                      | Start object tracking automatically (object tracking mode only)                   |
| `restartTracking`        | `boolean`                  | —                      | Re-attempt tracking after tracking loss recovery                                  |
| `trackingCaptureDelayMs` | `number`                   | `0`                    | Milliseconds to wait after session start before capturing for tracking            |
| `referenceSpaceType`     | `'local' \| 'local-floor'` | `'local'`              | XR reference space type                                                           |
| `framebufferScaleFactor` | `number`                   | —                      | XR framebuffer scale. Values below 1 reduce GPU load; values above 1 supersample. |

### Session Callbacks

#### Lifecycle

| Callback            | Arguments          | Description                                           |
| ------------------- | ------------------ | ----------------------------------------------------- |
| `onSessionStart`    | `()`               | AR session started                                    |
| `onSessionEnd`      | `()`               | AR session ended                                      |
| `onError`           | `(error: unknown)` | Any error in the session lifecycle                    |
| `onContextLost`     | `()`               | WebGL context lost. Session auto-ends.                |
| `onContextRestored` | `()`               | WebGL context restored. User can restart the session. |

#### VPS Localization

| Callback                | Arguments                              | Description                                             |
| ----------------------- | -------------------------------------- | ------------------------------------------------------- |
| `onLocalizationInit`    | `()`                                   | Localization request started                            |
| `onLocalizationResult`  | `(result: ILocalizeAndMapDetails)`     | Localization succeeded and passed confidence check      |
| `onLocalizationFailure` | `(reason?: string)`                    | Localization failed or was rejected by confidence check |
| `onFrameCaptured`       | `(frame: IFrameCaptureEvent)`          | Camera frame captured as a JPEG Blob                    |
| `onCameraIntrinsics`    | `(intrinsics: ICameraIntrinsicsEvent)` | Camera intrinsic parameters for the captured frame      |
| `onPoseResult`          | `(pose: IPoseResultEvent)`             | Raw pose from the API before confidence filtering       |

#### Object Tracking

| Callback                    | Arguments                           | Description                              |
| --------------------------- | ----------------------------------- | ---------------------------------------- |
| `onObjectTrackingInit`      | `()`                                | Object tracking request started          |
| `onObjectTrackingRequested` | `(frame, intrinsics)`               | Frame captured, request about to be sent |
| `onObjectTrackingSuccess`   | `(result: IObjectTrackingResponse)` | Object detected                          |
| `onObjectTrackingFailure`   | `(reason?: string)`                 | No object detected or request failed     |

### Static Methods

| Method                           | Returns            | Description                                |
| -------------------------------- | ------------------ | ------------------------------------------ |
| `XRSessionManager.isSupported()` | `Promise<boolean>` | Check if the browser supports immersive-ar |

### Instance Methods

| Method            | Returns                                    | Description                                                       |
| ----------------- | ------------------------------------------ | ----------------------------------------------------------------- |
| `startSession()`  | `Promise<void>`                            | Start the AR session. Must be called from a user gesture handler. |
| `stopSession()`   | `void`                                     | Stop the active session                                           |
| `createButton()`  | `HTMLButtonElement`                        | Return a pre-styled START AR / STOP AR button                     |
| `localizeFrame()` | `Promise<ILocalizeAndMapDetails \| null>`  | Capture and localize one frame. Session must be active.           |
| `trackObjects()`  | `Promise<IObjectTrackingResponse \| null>` | Capture and run object detection. Session must be active.         |
| `isActive()`      | `boolean`                                  | Whether an AR session is currently running                        |
| `getClient()`     | `MultisetClient`                           | Access the underlying HTTP client                                 |
| `dispose()`       | `void`                                     | End session, remove all event listeners, release GL resources     |

### Properties

| Property       | Type      | Description                                               |
| -------------- | --------- | --------------------------------------------------------- |
| `isLocalizing` | `boolean` | Whether a localization or tracking request is in progress |

### Adapter Hooks

For custom renderer adapters, register handlers that are called on key session events:

| Method                                      | Description                                                                          |
| ------------------------------------------- | ------------------------------------------------------------------------------------ |
| `setXRFrameHandler(handler)`                | Called every XR frame. Receives `IXRFrameEvent`.                                     |
| `setAdapterResultHandler(handler)`          | Called after successful VPS localization with the result and tracker reference space |
| `setAdapterObjectTrackingHandler(handler)`  | Called after successful object tracking with the result and tracker reference space  |
| `setAdapterSessionHandlers(onStart, onEnd)` | Called on session start and session end                                              |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.multiset.ai/webxr-sdk/api-reference/xrsessionmanager.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.