Embed-sessies

Een embed-sessie is de kortlevende toestemming waarmee een RealityTwin binnen uw pagina kan worden gerenderd. Uw backend maakt er een aan via de RealityConnect API, stuurt de browserveilige waarden door naar uw front-end, en uw front-end geeft ze door aan de SDK. Deze pagina is de referentie voor die twee endpoints, voor elk veld dat ze retourneren en voor de ene waarde die u zelf moet samenstellen: de iframe-URL.

---

De twee sessie-endpoints

Beide bewerkingen bevinden zich op de twin-context en zijn gepubliceerd in de interactieve API-referentie, gemarkeerd als experimenteel.

Methode	Pad	Body
GET	{api_url}/v1/twin/{contextId}/embed/create-session	Geen
POST	{api_url}/v1/twin/{contextId}/embed/refresh-session	{ "refreshToken": "<base64 refresh token>" }

{api_url} is uw regionale API-basis, die al eindigt op /realityconnect-api. Een volledige aanroep ziet er dus zo uit:

GET https://api-ue1.prevu3d.com/realityconnect-api/v1/twin/{contextId}/embed/create-session
Authorization: Bearer {access_token}

{contextId} is de ID van de twin die u wilt insluiten. RealityPlan wordt hier niet ondersteund.

Opgepast

Maak en vernieuw sessies vanuit uw eigen backend. Uw OAuth-clientgeheim en het refresh token mogen nooit de browser bereiken.

Vereiste scopes

Beide bewerkingen vereisen twee scopes op hetzelfde access token:

Scope	Waarom
read:twin	De twin lezen waarop de sessie betrekking heeft
embed:twin	Er een embed-sessie voor aanmaken

Een token met slechts één van de twee ontvangt 403 Forbidden met Insufficient OAuth scopes. Voeg beide toe aan uw OAuth-applicatie voordat u begint; zie de gids Client Credentials-flow.

Embed-sessies gebruiken bovendien een eigen, strakker rate-limit-budget dan de rest van de API: maak dus één sessie per kijksessie in plaats van per paginaweergave.

De create-session-response

{
  "iframeUrl": "https://embed.prevu3d.com/reality-twin",
  "token": "eyJhbGciOiJFUzUxMi...",
  "refreshToken": "ZXhhbXBsZS1yZWZyZXNoLXRva2Vu",
  "expiresAt": "2026-09-04T13:55:00.000Z",
  "apiUrl": "https://api-ue1.prevu3d.com/reality-twin"
}

Veld	Wat het is	SDK-configuratie
iframeUrl	De basis-URL van de embed-viewer. Vul deze aan vóór gebruik — zie De iframe-URL samenstellen.	iframeUrl, nadat u de embed-route hebt toegevoegd
token	Het ondertekende sessie-JWT. De SDK vereist het; de ingesloten twin authenticeert zich ermee.	platformJWT
refreshToken	Base64-geheim dat bij deze sessie hoort. Bewaar het op uw backend.	—
expiresAt	ISO 8601-tijdstempel waarvóór u de sessie moet vernieuwen — enkele minuten voordat token zelf niet langer wordt geaccepteerd.	—
apiUrl	De regionale RealityTwin-backend waarmee de ingesloten twin communiceert (…/reality-twin). Niet de {api_url} die u hierboven hebt aangeroepen — de sessie-endpoints bevinden zich daar niet.	backendUrl

refresh-session retourneert dezelfde vorm zonder iframeUrl en apiUrl. U hebt die twee maar één keer nodig: iframeUrl is constant binnen de omgeving en apiUrl is constant voor de regio van uw organisatie.

Opmerking

expiresAt is een bewust conservatieve schatting die wordt berekend wanneer de response wordt opgebouwd, en ligt enkele minuten vóór het eigen verlopen van het token. Beschouw het als het moment om te vernieuwen, niet als het exacte tijdstip waarop het token wordt afgewezen.

De iframe-URL samenstellen

iframeUrl is een basis-URL, geen afgeronde src. Het is dezelfde constante voor elke twin binnen een omgeving — in productie https://embed.prevu3d.com/reality-twin. Voeg de embed-route eraan toe:

const src = `${session.iframeUrl}/embed`;
// https://embed.prevu3d.com/reality-twin/embed

De twin-ID hoeft niet in de URL te staan — het sessietoken identificeert de twin al, en de viewer leest die daaruit.

Verbind de twee met precies één schuine streep: iframeUrl eindigt niet op een schuine streep, dus `${iframeUrl}/embed` is correct.

Geef de complete URL door aan de SDK:

RealityConnectEmbed.init({
  iframeUrl: `${session.iframeUrl}/embed`,
  backendUrl: session.apiUrl,
  platformJWT: session.token,
  elementId: 'twin-container',
});

Opgepast

iframeUrl ongewijzigd doorgeven laadt de twin-viewer helemaal niet. De waarde eindigt niet op een schuine streep, en op de embed-host wordt precies dat pad door een andere applicatie bediend — alleen paden daaronder bereiken de viewer. De handshake van de SDK heeft dan niets om mee te communiceren, dus onReady wordt nooit geactiveerd en de SDK meldt TWIN_TIMEOUT zodra de ready-timeout is verstreken.

Het token staat nooit in de URL

Het sessie-JWT reist naar het iframe via de INIT_CONFIG-postMessage-handshake van de SDK, als de configuratiewaarde platformJWT. Voeg het niet als queryparameter toe aan de iframe-URL — de ingesloten twin leest die niet, en een actieve credential in een URL plaatsen stelt deze bloot aan browsergeschiedenis, referrer-headers en serverlogs.

Om dezelfde reden verwacht de embed-pagina dat zij binnen het iframe van de SDK draait. Een complete URL op zichzelf in een browsertabblad plakken laadt geen twin, omdat er dan niets is dat het token en de backend-URL aanreikt.

De sessie in leven houden

Sessies zijn kortlevend. Roep vóór expiresAt vanuit uw backend refresh-session aan met het opgeslagen refreshToken, bewaar het nieuwe en geef het nieuwe token door aan de actieve SDK met twin.updateAccessToken(newAccessToken) — het iframe hoeft niet opnieuw te worden aangemaakt. Zie Stap 4 van Aan de slag voor het volledige patroon.

Volgende stappen

• Aan de slag: de end-to-end-integratie die deze referentie ondersteunt.
• Client Credentials-flow: hoe u het access token verkrijgt dat deze aanroepen nodig hebben.
• Interactieve API-referentie: het gepubliceerde schema voor beide bewerkingen.