Erste Schritte

Diese Anleitung führt durch die beiden Integrationen, die zum Einbetten eines RealityTwin erforderlich sind: das Erstellen einer Embed-Sitzung über die RealityConnect API (von Ihrem Backend) und das Übergeben dieser Sitzung an das SDK (in Ihrem Frontend). Alles, was speziell das SDK selbst betrifft – Installationsdetails, Initialisierung, die vollständige Befehls- und Observable-Oberfläche, Fehlercodes und den ausführbaren Playground – befindet sich im README des Pakets @prevu3d/realityconnect-embed, das die maßgebliche Quelle ist.

Tipp

Eine vollständige Vue.js-Integration ist unter rcembed-example.prevu3d.io bereitgestellt und ihr Quellcode befindet sich auf GitHub unter prevu3d/realityconnect-embed-example. Wenn Sie lieber eine funktionierende Konfiguration kopieren, als eine von Grund auf neu zu erstellen, beginnen Sie dort.

---

Voraussetzungen

Stellen Sie vor dem Start sicher, dass Sie über Folgendes verfügen:

• Einen Enterprise-Tarif mit RealityConnect Embed, der in den Sicherheitseinstellungen Ihrer Organisation aktiviert ist.
• Eine RealityConnect API-OAuth-Anwendung, die den Client-Credentials-Flow verwendet. Falls Sie noch keine eingerichtet haben, folgen Sie zuerst der Anleitung Client-Credentials-Flow.
• Die ID des Zwillings, den Sie einbetten möchten.
• Lesezugriff auf das private GitHub-Repository prevu3d/realityconnect-embed für das Konto, das das SDK installieren wird. Der Zugriff wird manuell pro Kunde auf Anfrage gewährt – kontaktieren Sie Ihren Customer Success Manager (CSM) mit den GitHub-Benutzernamen, die Zugriff benötigen, und Prevu3D fügt sie dem Repository hinzu. Die Paket-Sichtbarkeit auf GitHub Packages folgt der Repository-Sichtbarkeit, daher reicht ein read:packages-PAT allein nicht aus – Repository-Zugriff ist ebenfalls erforderlich.

Wie es zusammenpasst

Auf hoher Ebene läuft eine Embed-Sitzung wie folgt ab:

1. Ihr Backend authentifiziert sich bei der RealityConnect API und ruft create-session für einen bestimmten Zwilling auf. Die API gibt Tokens und URLs zurück.
2. Ihr Backend leitet die browsersicheren Werte (das Access Token, die Frontend-URL und die regionale API-URL) an Ihr Frontend weiter.
3. Ihr Frontend übergibt diese Werte an das SDK, das den iframe einfügt und einen bidirektionalen Kanal mit dem Zwilling öffnet.
4. Bevor das aktuelle Token abläuft, ruft Ihr Backend refresh-session auf und übergibt die neuen Werte zurück an das Frontend.

Ihr OAuth-Client-Secret darf niemals den Browser erreichen – nur Ihr Backend verwendet es.

Schritt 1: Eine Embed-Sitzung erstellen (Backend)

Die Verwaltung von Embed-Sitzungen nutzt die RealityConnect API wieder. Authentifizieren Sie sich mit dem Client-Credentials-Flow genau wie in der Anleitung Client-Credentials-Flow beschrieben und rufen Sie dann die beiden Embed-Sitzungs-Operationen für den Zwilling auf:

Operation	Zweck
POST {apiUrl}/twin/{twinId}/create-session	Startet eine Sitzung. Gibt accessToken, refreshToken, frontendUrl und apiUrl zurück.
POST {apiUrl}/twin/{twinId}/refresh-session	Tauscht ein refreshToken (im Body gesendet) gegen ein neues accessToken und refreshToken.

Beide Aufrufe verwenden das Bearer-Access-Token aus dem Client-Credentials-Flow im Authorization-Header. Siehe die interaktive API-Referenz für die genauen Pfade und Schemata.

Achtung

Fordern und erneuern Sie Embed-Sitzungen immer von Ihrem eigenen Backend aus. Ihr OAuth-Client-Secret und Ihre Access Tokens dürfen niemals den Browser erreichen. Der Browser erhält nur die Werte, die Ihr Backend an ihn weiterzugeben beschließt.

Schritt 2: Das SDK installieren (Frontend)

Sobald Ihrem GitHub-Konto der Zugriff gewährt wurde (siehe Voraussetzungen), installieren Sie das SDK aus der privaten GitHub-Packages-npm-Registry als @prevu3d/realityconnect-embed. Das SDK-README dokumentiert die einmalige Einrichtung von .npmrc und Personal Access Token von Anfang bis Ende.

Schritt 3: Die Sitzung an das SDK übergeben

Leiten Sie die Felder der create-session-Antwort von Ihrem Backend an Ihr Frontend weiter und ordnen Sie sie der SDK-Konfiguration zu:

create-session-Feld	SDK-Konfiguration	Notizen
frontendUrl	iframeUrl	Hängen Sie die Embed-Route und die Zwilling-ID an: `${frontendUrl}/embed/${twinId}`.
apiUrl	backendUrl	Die regionale API-Basis, mit der der Embed kommuniziert.
accessToken	platformJWT	Das signierte Sitzungs-Token, mit dem sich der Embed authentifiziert.

Von dort aus folgen Sie dem SDK-README, um das Paket zu installieren, den Viewer zu initialisieren und den Zwilling zu steuern.

Schritt 4: Die Sitzung aufrechterhalten

Embed-Sitzungen sind kurzlebig – das von create-session zurückgegebene accessToken läuft nach einer gewissen Zeit ab. Um den Zwilling über dieses Zeitfenster hinaus in Betrieb zu halten, erneuern Sie die Sitzung von Ihrem Backend aus und übergeben Sie das neue Access-Token an das laufende SDK – kein erneutes Erstellen des iframe erforderlich.

Ein gängiges Muster:

1. Stellen Sie im Backend einen Endpoint bereit, der das gespeicherte refreshToken für den Zwilling des aktuellen Benutzers liest, refresh-session aufruft, das neue refreshToken persistiert und das neue accessToken (und die anderen Sitzungsfelder) an den Browser zurückgibt.

2. Planen Sie im Frontend eine Erneuerung kurz vor Ablauf des aktuellen Tokens.

3. Wenn die neue Sitzung eintrifft, übergeben Sie das neue Access-Token an das laufende SDK, indem Sie twin.updateAccessToken(newAccessToken) aufrufen:

   await twin.updateAccessToken(newAccessToken);

   Der Zwilling führt das neue JWT in seiner nächsten Backend-Anfrage weiter – offene Abonnements, Kamerastatus und der geladene Workflow bleiben erhalten. Der Aufruf wird bei Annahme mit true und bei Ablehnung mit false aufgelöst (wird auch über onError signalisiert); ein Aufruf vor dem Auslösen von onReady löst RealityConnectEmbedError('TWIN_NOT_READY') aus.

Die genaue Planungsstrategie (fester Timer vor Ablauf, bei Benutzeraktivität, bei Änderung der Tab-Sichtbarkeit usw.) liegt bei Ihrer Anwendung.

Was Sie beachten sollten

• Ihre Seite besitzt die Oberfläche. Der Embed ist ein nackter Viewer – erstellen Sie Ihre eigenen Steuerelemente und verbinden Sie sie mit SDK-Befehlen. Siehe die Einführung dazu, was der Embed enthält und was nicht.
• Halten Sie Anmeldedaten serverseitig. Fordern und erneuern Sie Sitzungen nur von Ihrem Backend aus.
• Sitzungen laufen ab. Planen Sie die Token-Erneuerung als Teil Ihrer Integration ein.
• Enterprise- und Sicherheitseinstellungen. Der Embed wird nur geladen, wenn er für Ihre Organisation aktiviert ist.

SDK-Referenz

Das Paket @prevu3d/realityconnect-embed ist die vollständige Referenz für die Arbeit mit dem SDK. Lesen Sie sein README für:

• Die vollständige Einrichtung von .npmrc und Personal Access Token für die private GitHub-Packages-Registry
• Die Konfigurationsreferenz RealityConnectEmbed.init(config)
• Die Aktionen und Zustands-Observables jedes Namespace (Navigation, Objekte, POI, POV, Utilities)
• Den Kameraansichts-Kodierungs-Flow für teilbare Links
• Alle dokumentierten Fehlercodes und wann sie ausgelöst werden
• Einen ausführbaren Playground, den Sie auf einen Live-Zwilling richten können, um die Befehlsoberfläche zu erkunden

Nächste Schritte

• Einführung – Überblick über die Funktionen.
• Client-Credentials-Flow – die Authentifizierung, auf der diese Anleitung aufbaut.
• Interaktive API-Referenz – der vollständige Katalog der RealityConnect API.
• Live-Beispiel auf GitHub – eine funktionierende Vue.js-Integration, die Sie kopieren können.
• @prevu3d/realityconnect-embed – Quellcode-Repository