Getting Started

This guide walks through the two integrations you need to embed a RealityTwin: creating an embed session against the RealityConnect API (from your backend) and handing that session to the SDK (in your front-end). Everything specific to the SDK itself — installation details, initialization, the full command and observable surface, error codes, and the runnable playground — lives in the @prevu3d/realityconnect-embed package README, which is the source of truth.

Prerequisites

Before you start, make sure you have:

An Enterprise plan with RealityConnect Embed enabled in your organization’s Security settings.
A RealityConnect API OAuth application using the Client Credentials flow. If you haven’t set one up, follow the Client Credentials Flow guide first.
The ID of the twin you want to embed.
Read access to the private prevu3d/realityconnect-embed GitHub repository for the account that will install the SDK. Access is granted manually per customer on request — contact your Customer Success Manager (CSM) with the GitHub usernames that need access, and Prevu3D will add them to the repository. Package visibility on GitHub Packages follows repo visibility, so a read:packages PAT alone is not enough — repo access is also required.

How it fits together

At a high level, an embed session flows like this:

Your backend authenticates against the RealityConnect API and calls create-session for a specific twin. The API returns tokens and URLs.
Your backend forwards the browser-safe values (the access token, the frontend URL, and the regional API URL) to your front-end.
Your front-end passes those values to the SDK, which injects the iframe and opens a two-way channel with the twin.
Before the current token expires, your backend calls refresh-session and hands the fresh values back to the front-end.

Your OAuth client secret must never reach the browser — only your backend uses it.

Step 1: Create an embed session (backend)

Embed session management reuses the RealityConnect API. Authenticate with the Client Credentials flow exactly as described in the Client Credentials Flow guide, then call the two embed-session operations on the twin:

Operation	Purpose
`POST {apiUrl}/twin/{twinId}/create-session`	Starts a session. Returns `accessToken`, `refreshToken`, `frontendUrl`, and `apiUrl`.
`POST {apiUrl}/twin/{twinId}/refresh-session`	Exchanges a `refreshToken` (sent in the body) for a fresh `accessToken` and `refreshToken`.

Both calls use the bearer access token from the Client Credentials flow in the Authorization header. See the interactive API reference for the exact paths and schemas.

Step 2: Install the SDK (front-end)

Once your GitHub account has been granted access (see Prerequisites), install the SDK from the private GitHub Packages npm registry as @prevu3d/realityconnect-embed. The SDK README documents the one-time .npmrc and Personal Access Token setup end to end.

Step 3: Hand the session to the SDK

Forward the create-session response fields from your backend to your front-end and map them onto the SDK’s configuration:

`create-session` field	SDK config	Notes
`frontendUrl`	`iframeUrl`	Append the embed route and twin ID: `${frontendUrl}/embed/${twinId}`.
`apiUrl`	`backendUrl`	The regional API base the embed talks to.
`accessToken`	`platformJWT`	The signed session token the embed authenticates with.

From there, follow the SDK README to install the package, initialize the viewer, and drive the twin.

Step 4: Keep the session alive

Embed sessions are short-lived — the accessToken returned by create-session expires after a period of time. To keep the twin running past that window, refresh the session from your backend and hand the new access token to the running SDK — no need to recreate the iframe.

A common pattern:

On the backend, expose an endpoint that reads the stored refreshToken for the current user’s twin, calls refresh-session, persists the new refreshToken, and returns the new accessToken (and other session fields) to the browser.
On the front-end, schedule a refresh shortly before the current token expires.
When the fresh session arrives, hand the new access token to the running SDK by calling twin.updateAccessToken(newAccessToken):
```
await twin.updateAccessToken(newAccessToken);
```
The twin threads the new JWT through its next backend request — open subscriptions, camera state, and the loaded workflow all survive. The call resolves true on acceptance and false on rejection (also surfaced via onError); calling it before onReady fires throws RealityConnectEmbedError('TWIN_NOT_READY').

The exact scheduling strategy (fixed timer before expiry, on user activity, on tab visibility change, etc.) is up to your application.

Things to be aware of

Your page owns the interface. The embed is a bare viewer — build your own controls and wire them to SDK commands. See the Introduction for what the embed does and doesn’t include.
Keep credentials server-side. Request and refresh sessions from your backend only.
Sessions expire. Plan for token refresh as part of your integration.
Enterprise and Security settings. The embed loads only when enabled for your organization.

SDK reference

The @prevu3d/realityconnect-embed package is the complete reference for working with the SDK. Read its README for:

Full .npmrc and Personal Access Token setup for the private GitHub Packages registry
The RealityConnectEmbed.init(config) configuration reference
Every namespace’s actions and state observables (navigation, objects, POI, POV, utilities)
The camera view-encoding flow for shareable links
All documented error codes and when they fire
A runnable playground you can point at a live twin to explore the command surface

Next steps

Introduction — capabilities overview.
Client Credentials Flow — the authentication this guide builds on.
Interactive API reference — the full RealityConnect API catalog.
Live example on GitHub — a working Vue.js integration you can copy from.
@prevu3d/realityconnect-embed - Sources repository