Sessions d'embed

Une session d’embed est l’autorisation de courte durée qui permet à un RealityTwin de s’afficher dans votre page. Votre back-end en crée une via la RealityConnect API, transmet les valeurs utilisables côté navigateur à votre front-end, et votre front-end les remet au SDK. Cette page est la référence de ces deux points de terminaison, de chacun des champs qu’ils renvoient et de la seule valeur que vous devez assembler vous-même : l’URL de l’iframe.

---

Les deux points de terminaison de session

Les deux opérations s’appliquent au contexte du jumeau et sont publiées dans la référence interactive de l’API, marquées expérimentales.

Méthode	Chemin	Corps
GET	{api_url}/v1/twin/{contextId}/embed/create-session	Aucun
POST	{api_url}/v1/twin/{contextId}/embed/refresh-session	{ "refreshToken": "<base64 refresh token>" }

{api_url} est votre base d’API régionale, qui se termine déjà par /realityconnect-api. Un appel complet ressemble donc à ceci :

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

{contextId} est l’ID du jumeau que vous souhaitez intégrer. RealityPlan n’est pas pris en charge ici.

Attention

Créez et rafraîchissez les sessions depuis votre propre back-end. Votre client secret OAuth et le refresh token ne doivent jamais parvenir au navigateur.

Scopes requis

Les deux opérations exigent deux scopes sur le même jeton d’accès :

Scope	Pourquoi
read:twin	Lire le jumeau ciblé par la session
embed:twin	Émettre une session d’embed pour ce jumeau

Un jeton ne portant qu’un seul des deux reçoit 403 Forbidden avec Insufficient OAuth scopes. Ajoutez les deux à votre application OAuth avant de commencer ; consultez le guide Flux Client Credentials.

Les sessions d’embed utilisent par ailleurs un budget de limite de débit dédié et plus strict que le reste de l’API : créez donc une session par session de consultation plutôt qu’à chaque rendu de page.

La réponse de create-session

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

Champ	De quoi il s’agit	Config du SDK
iframeUrl	L’URL de base du visualiseur d’embed. Complétez-la avant de l’utiliser — voir Construire l’URL de l’iframe.	iframeUrl, une fois la route d’embed ajoutée
token	Le JWT de session signé. Le SDK l’exige ; le jumeau intégré s’authentifie avec lui.	platformJWT
refreshToken	Secret en base64 associé à cette session. Conservez-le sur votre back-end.	—
expiresAt	Horodatage ISO 8601 avant lequel rafraîchir la session — quelques minutes avant que token lui-même cesse d’être accepté.	—
apiUrl	Le back-end RealityTwin régional auquel le jumeau intégré s’adresse (…/reality-twin). Ce n’est pas le {api_url} appelé ci-dessus — les points de terminaison de session ne s’y trouvent pas.	backendUrl

refresh-session renvoie la même structure sans iframeUrl ni apiUrl. Vous n’avez besoin de ces deux valeurs qu’une seule fois : iframeUrl est constante pour l’environnement, et apiUrl est constante pour la région de votre organisation.

Note

expiresAt est une estimation volontairement prudente, calculée au moment où la réponse est construite, et se situe quelques minutes avant l’expiration réelle du jeton. Considérez-la comme le moment de rafraîchir, et non comme l’instant exact où le jeton cesse d’être accepté.

Construire l’URL de l’iframe

iframeUrl est une URL de base, pas un src terminé. C’est la même constante pour chaque jumeau au sein d’un environnement — en production, https://embed.prevu3d.com/reality-twin. Ajoutez-y la route d’embed :

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

L’ID du jumeau n’est pas nécessaire dans l’URL — le jeton de session identifie déjà le jumeau, et le visualiseur l’y lit.

Joignez les deux avec exactement une barre oblique : iframeUrl ne se termine pas par une barre oblique, donc `${iframeUrl}/embed` est correct.

Transmettez l’URL complétée au SDK :

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

Attention

Transmettre iframeUrl telle quelle ne charge pas du tout le visualiseur du jumeau. La valeur ne se termine pas par une barre oblique, et sur l’hôte d’embed ce chemin exact est servi par une autre application — seuls les chemins situés en dessous atteignent le visualiseur. La poignée de main du SDK n’a alors aucun interlocuteur : onReady ne se déclenche jamais et le SDK signale TWIN_TIMEOUT une fois son délai d’attente écoulé.

Le jeton ne circule jamais dans l’URL

Le JWT de session parvient à l’iframe via la poignée de main postMessage INIT_CONFIG du SDK, sous la forme de la valeur de configuration platformJWT. Ne l’ajoutez pas à l’URL de l’iframe sous forme de paramètre de requête — le jumeau intégré n’en lit aucun, et placer un identifiant actif dans une URL l’expose à l’historique du navigateur, aux en-têtes referrer et aux journaux serveur.

Pour la même raison, la page d’embed s’exécute nécessairement dans l’iframe du SDK. Coller une URL complétée dans un onglet de navigateur seul ne charge aucun jumeau, car rien ne s’y trouve pour lui transmettre le jeton et l’URL du back-end.

Maintenir la session active

Les sessions sont de courte durée. Avant expiresAt, appelez refresh-session depuis votre back-end avec le refreshToken stocké, persistez le nouveau, puis transmettez le nouveau token au SDK en cours d’exécution avec twin.updateAccessToken(newAccessToken) — inutile de recréer l’iframe. Consultez l’Étape 4 des Premiers pas pour le schéma complet.

Prochaines étapes

• Premiers pas : l’intégration de bout en bout que cette référence accompagne.
• Flux Client Credentials : comment obtenir le jeton d’accès requis par ces appels.
• Référence interactive de l’API : le schéma publié des deux opérations.