Aan de slag

Deze gids doorloopt de twee integraties die u nodig hebt om een RealityTwin in te sluiten: een embed-sessie aanmaken tegen de RealityConnect API (vanuit uw backend) en die sessie doorgeven aan de SDK (in uw front-end). Alles wat specifiek is voor de SDK zelf — installatiedetails, initialisatie, het volledige opdracht- en observable-oppervlak, foutcodes en de uitvoerbare playground — staat in de README van het pakket @prevu3d/realityconnect-embed, die de gezaghebbende bron is.

Vereisten

Zorg dat u het volgende hebt voordat u begint:

Een Enterprise-abonnement met RealityConnect Embed ingeschakeld in de Beveiligingsinstellingen van uw organisatie.
Een RealityConnect API OAuth-applicatie die de Client Credentials-flow gebruikt. Als u er nog geen hebt ingesteld, volg dan eerst de gids Client Credentials-flow.
De ID van de twin die u wilt insluiten.
Leestoegang tot de privé-GitHub-repository prevu3d/realityconnect-embed voor het account dat de SDK zal installeren. Toegang wordt handmatig per klant op verzoek verleend — neem contact op met uw Customer Success Manager (CSM) met de GitHub-gebruikersnamen die toegang nodig hebben, en Prevu3D voegt ze toe aan de repository. De zichtbaarheid van het pakket op GitHub Packages volgt de zichtbaarheid van de repository, dus een read:packages-PAT alleen is niet voldoende — repository-toegang is ook vereist.

Hoe alles samenwerkt

Op hoofdlijnen verloopt een embed-sessie als volgt:

Uw backend authenticeert zich bij de RealityConnect API en roept create-session aan voor een specifieke twin. De API retourneert tokens en URL’s.
Uw backend stuurt de browserveilige waarden (het sessietoken, de basis-URL van het iframe en de regionale API-URL) door naar uw front-end.
Uw front-end geeft die waarden door aan de SDK, die het iframe injecteert en een tweerichtingskanaal met de twin opent.
Voordat het huidige token verloopt, roept uw backend refresh-session aan en geeft de nieuwe waarden terug aan de front-end.

Uw OAuth-clientgeheim mag nooit de browser bereiken — alleen uw backend gebruikt het.

Stap 1: Een embed-sessie aanmaken (backend)

Het beheer van embed-sessies hergebruikt de RealityConnect API. Authenticeer met de Client Credentials-flow precies zoals beschreven in de gids Client Credentials-flow en roep vervolgens de twee embed-sessiebewerkingen op de twin aan:

Bewerking	Doel
`GET {api_url}/v1/twin/{contextId}/embed/create-session`	Start een sessie. Retourneert `iframeUrl`, `token`, `refreshToken`, `expiresAt` en `apiUrl`. Heeft geen body.
`POST {api_url}/v1/twin/{contextId}/embed/refresh-session`	Wisselt een `refreshToken` (in de body verzonden) in voor een nieuw `token` en `refreshToken`.

Beide aanroepen gebruiken het bearer-access-token uit de Client Credentials-flow in de Authorization-header, en beide vereisen de scopes read:twin en embed:twin op dat token. Embed-sessies is de volledige referentie voor deze twee bewerkingen; de interactieve API-referentie publiceert hun schema’s.

Stap 2: De SDK installeren (front-end)

Zodra uw GitHub-account toegang heeft gekregen (zie Vereisten), installeert u de SDK vanuit de privé-npm-registry van GitHub Packages als @prevu3d/realityconnect-embed. De SDK-README documenteert de eenmalige .npmrc- en Personal Access Token-configuratie van begin tot eind.

Stap 3: De sessie doorgeven aan de SDK

Stuur de velden van de create-session-respons door van uw backend naar uw front-end en koppel ze aan de configuratie van de SDK:

Veld van `create-session`	SDK-configuratie	Opmerkingen
`iframeUrl`	`iframeUrl`	Een basis-URL. Voeg zelf de embed-route toe: `${iframeUrl}/embed`. De twin-ID hoort niet in de URL — het sessietoken identificeert de twin. Zie De iframe-URL samenstellen.
`apiUrl`	`backendUrl`	De regionale RealityTwin-backend waarmee de embed communiceert. Niet de `{api_url}` die u in Stap 1 hebt aangeroepen.
`token`	`platformJWT`	Het ondertekende sessietoken waarmee de embed zich authenticeert. Wordt door de SDK aan het iframe geleverd, nooit als URL-parameter.

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

Volg vanaf daar de SDK-README om het pakket te installeren, de viewer te initialiseren en de twin aan te sturen.

Stap 4: De sessie in leven houden

Embed-sessies zijn kortlevend — het token dat door create-session wordt geretourneerd, verloopt ongeveer op de expiresAt die het meldt. Om de twin voorbij dat venster in bedrijf te houden, vernieuwt u de sessie vanuit uw backend en geeft u het nieuwe access token door aan de actieve SDK — het iframe hoeft niet opnieuw te worden aangemaakt.

Een veelgebruikt patroon:

Stel op de backend een endpoint beschikbaar dat het opgeslagen refreshToken voor de twin van de huidige gebruiker leest, refresh-session aanroept, het nieuwe refreshToken bewaart en het nieuwe token (en de overige sessievelden) teruggeeft aan de browser.
Plan op de front-end een vernieuwing kort voordat het huidige token verloopt.
Wanneer de nieuwe sessie binnenkomt, geeft u het nieuwe access token door aan de actieve SDK door twin.updateAccessToken(newAccessToken) aan te roepen:
```
await twin.updateAccessToken(newAccessToken);
```
De twin geeft het nieuwe JWT door in de volgende backend-aanvraag — open abonnementen, camerastatus en de geladen workflow blijven behouden. De aanroep wordt bij acceptatie opgelost met true en bij afwijzing met false (ook gemeld via onError); als u het aanroept voordat onReady afgaat, wordt RealityConnectEmbedError('TWIN_NOT_READY') gegooid.

De exacte planningsstrategie (vaste timer vóór het verlopen, bij gebruikersactiviteit, bij wijziging van de tabbladzichtbaarheid, enz.) is aan uw applicatie.

Aandachtspunten

Uw pagina bezit de interface. De embed is een kale viewer — bouw uw eigen bedieningselementen en koppel ze aan SDK-opdrachten. Zie de Introductie voor wat de embed wel en niet omvat.
Houd referenties aan de serverzijde. Vraag en vernieuw sessies alleen vanuit uw backend.
Sessies verlopen. Reken op tokenvernieuwing als onderdeel van uw integratie.
Enterprise- en Beveiligingsinstellingen. De embed wordt alleen geladen wanneer die is ingeschakeld voor uw organisatie.

SDK-referentie

Het pakket @prevu3d/realityconnect-embed is de volledige referentie voor het werken met de SDK. Lees de README ervan voor:

De volledige .npmrc- en Personal Access Token-configuratie voor de privé-registry van GitHub Packages
De configuratiereferentie RealityConnectEmbed.init(config)
De acties en status-observables van elke namespace (navigatie, objecten, POI, POV, hulpprogramma’s)
De cameraweergave-coderingsflow voor deelbare links
Alle gedocumenteerde foutcodes en wanneer ze worden geactiveerd
Een uitvoerbare playground die u op een live twin kunt richten om het opdrachtoppervlak te verkennen

Volgende stappen

Embed-sessies: de sessie-endpoints, elk responseveld en hoe u de iframe-URL samenstelt.
Introductie: overzicht van de mogelijkheden.
Client Credentials-flow: de authenticatie waarop deze gids voortbouwt.
Interactieve API-referentie: de volledige catalogus van de RealityConnect API.
Live voorbeeld op GitHub: een werkende Vue.js-integratie die u kunt kopiëren.
@prevu3d/realityconnect-embed: broncoderepository