Embed-Sitzungen

Eine Embed-Sitzung ist die kurzlebige Berechtigung, mit der ein RealityTwin in Ihrer Seite gerendert werden kann. Ihr Backend erstellt sie über die RealityConnect API, leitet die browsersicheren Werte an Ihr Frontend weiter, und Ihr Frontend übergibt sie an das SDK. Diese Seite ist die Referenz für diese beiden Endpunkte, für jedes Feld, das sie zurückgeben, und für den einen Wert, den Sie selbst zusammensetzen müssen: die iframe-URL.

---

Die beiden Sitzungs-Endpunkte

Beide Operationen liegen auf dem Zwilling-Kontext und sind in der interaktiven API-Referenz veröffentlicht, gekennzeichnet als experimentell.

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

{api_url} ist Ihre regionale API-Basis, die bereits auf /realityconnect-api endet. Ein vollständiger Aufruf sieht daher so aus:

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

{contextId} ist die ID des Zwillings, den Sie einbetten möchten. RealityPlan wird hier nicht unterstützt.

Achtung

Erstellen und erneuern Sie Sitzungen ausschließlich von Ihrem eigenen Backend aus. Ihr OAuth-Client-Secret und das Refresh Token dürfen niemals den Browser erreichen.

Erforderliche Scopes

Beide Operationen erfordern zwei Scopes auf demselben Access Token:

Scope	Wofür
read:twin	Den Zwilling lesen, auf den die Sitzung abzielt
embed:twin	Eine Embed-Sitzung dafür ausstellen

Ein Token, das nur einen der beiden enthält, erhält 403 Forbidden mit Insufficient OAuth scopes. Fügen Sie beide zu Ihrer OAuth-Anwendung hinzu, bevor Sie beginnen; siehe die Anleitung Client-Credentials-Flow.

Embed-Sitzungen nutzen außerdem ein eigenes, engeres Rate-Limit-Budget als der Rest der API. Erstellen Sie deshalb eine Sitzung pro Betrachtungssitzung und nicht pro Seitenaufruf.

Die create-session-Antwort

{
  "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"
}

Feld	Was es ist	SDK-Konfiguration
iframeUrl	Die Basis-URL des Embed-Viewers. Vervollständigen Sie sie vor der Verwendung – siehe Die iframe-URL zusammensetzen.	iframeUrl, nachdem Sie die Embed-Route angehängt haben
token	Das signierte Sitzungs-JWT. Das SDK benötigt es; der eingebettete Zwilling authentifiziert sich damit.	platformJWT
refreshToken	Base64-Secret, das zu dieser Sitzung gehört. Bewahren Sie es in Ihrem Backend auf.	–
expiresAt	ISO-8601-Zeitstempel, bis zu dem Sie die Sitzung erneuern sollten – einige Minuten, bevor token selbst nicht mehr akzeptiert wird.	–
apiUrl	Das regionale RealityTwin-Backend, mit dem der eingebettete Zwilling kommuniziert (…/reality-twin). Nicht die {api_url}, die Sie oben aufgerufen haben – die Sitzungs-Endpunkte liegen nicht darauf.	backendUrl

refresh-session gibt dieselbe Struktur ohne iframeUrl und apiUrl zurück. Sie benötigen diese beiden nur einmal: iframeUrl ist innerhalb einer Umgebung konstant, und apiUrl ist für die Region Ihrer Organisation konstant.

Hinweis

expiresAt ist eine bewusst konservative Schätzung, die beim Erstellen der Antwort berechnet wird, und liegt einige Minuten vor dem eigentlichen Ablauf des Tokens. Betrachten Sie den Wert als den Zeitpunkt zum Erneuern, nicht als den exakten Moment, an dem das Token seine Gültigkeit verliert.

Die iframe-URL zusammensetzen

iframeUrl ist eine Basis-URL, kein fertiges src. Sie ist innerhalb einer Umgebung für jeden Zwilling dieselbe Konstante – in der Produktion https://embed.prevu3d.com/reality-twin. Hängen Sie die Embed-Route daran an:

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

Die Zwilling-ID muss nicht in der URL stehen – das Sitzungs-Token identifiziert den Zwilling bereits, und der Viewer liest ihn daraus.

Verbinden Sie beide mit genau einem Schrägstrich: iframeUrl endet ohne Schrägstrich, `${iframeUrl}/embed` ist also korrekt.

Übergeben Sie die vollständige URL an das SDK:

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

Achtung

Wenn Sie iframeUrl unverändert weiterreichen, wird der Zwilling-Viewer überhaupt nicht geladen. Der Wert endet ohne Schrägstrich, und auf dem Embed-Host wird genau dieser Pfad von einer anderen Anwendung ausgeliefert – nur Pfade darunter erreichen den Viewer. Der Handshake des SDK hat dann kein Gegenüber, onReady wird deshalb nie ausgelöst, und das SDK meldet TWIN_TIMEOUT, sobald sein Ready-Timeout abgelaufen ist.

Das Token steht nie in der URL

Das Sitzungs-JWT gelangt über den INIT_CONFIG-postMessage-Handshake des SDK zum iframe, als Konfigurationswert platformJWT. Hängen Sie es nicht als Query-Parameter an die iframe-URL an – der eingebettete Zwilling liest keinen solchen Parameter, und ein aktives Credential in einer URL gelangt so in Browserverlauf, Referrer-Header und Server-Logs.

Aus demselben Grund erwartet die Embed-Seite, innerhalb des iframe des SDK zu laufen. Eine vollständige URL, die Sie für sich allein in einen Browser-Tab einfügen, lädt keinen Zwilling, weil dort nichts vorhanden ist, das ihr das Token und die Backend-URL übergibt.

Die Sitzung aufrechterhalten

Sitzungen sind kurzlebig. Rufen Sie vor expiresAt von Ihrem Backend aus refresh-session mit dem gespeicherten refreshToken auf, persistieren Sie das neue und übergeben Sie das neue token mit twin.updateAccessToken(newAccessToken) an das laufende SDK – der iframe muss nicht neu erstellt werden. Siehe Schritt 4 von Erste Schritte für das vollständige Muster.

Nächste Schritte

• Erste Schritte – die durchgängige Integration, die diese Referenz unterstützt.
• Client-Credentials-Flow – wie Sie das Access Token erhalten, das diese Aufrufe benötigen.
• Interaktive API-Referenz – das veröffentlichte Schema für beide Operationen.