Premiers pas

Ce guide décrit les deux intégrations nécessaires pour intégrer un RealityTwin : créer une session d’embed auprès de la RealityConnect API (depuis votre back-end) et transmettre cette session au SDK (dans votre front-end). Tout ce qui est propre au SDK lui-même — détails d’installation, initialisation, surface complète des commandes et observables, codes d’erreur et bac à sable exécutable — se trouve dans le README du package @prevu3d/realityconnect-embed, qui fait référence.

Prérequis

Avant de commencer, assurez-vous de disposer de :

Un forfait Enterprise avec RealityConnect Embed activé dans les paramètres de Sécurité de votre organisation.
Une application OAuth RealityConnect API utilisant le flux Client Credentials. Si vous n’en avez pas encore configuré, suivez d’abord le guide Flux Client Credentials.
L’ID du jumeau que vous souhaitez intégrer.
Un accès en lecture au dépôt GitHub privé prevu3d/realityconnect-embed pour le compte qui installera le SDK. L’accès est accordé manuellement par client sur demande — contactez votre Customer Success Manager (CSM) avec les noms d’utilisateur GitHub qui ont besoin d’un accès, et Prevu3D les ajoutera au dépôt. La visibilité du package sur GitHub Packages suit la visibilité du dépôt : un PAT read:packages seul ne suffit donc pas — l’accès au dépôt est également requis.

Comment cela s’assemble

À un niveau élevé, une session d’embed se déroule ainsi :

Votre back-end s’authentifie auprès de la RealityConnect API et appelle create-session pour un jumeau spécifique. L’API renvoie des jetons et des URL.
Votre back-end transmet les valeurs utilisables côté navigateur (le jeton de session, l’URL de base de l’iframe et l’URL régionale de l’API) à votre front-end.
Votre front-end transmet ces valeurs au SDK, qui injecte l’iframe et ouvre un canal bidirectionnel avec le jumeau.
Avant l’expiration du jeton courant, votre back-end appelle refresh-session et retransmet les nouvelles valeurs au front-end.

Votre client secret OAuth ne doit jamais parvenir au navigateur — seul votre back-end l’utilise.

Étape 1 : Créer une session d’embed (back-end)

La gestion des sessions d’embed réutilise la RealityConnect API. Authentifiez-vous avec le flux Client Credentials exactement comme décrit dans le guide Flux Client Credentials, puis appelez les deux opérations de session d’embed sur le jumeau :

Opération	Objectif
`GET {api_url}/v1/twin/{contextId}/embed/create-session`	Démarre une session. Renvoie `iframeUrl`, `token`, `refreshToken`, `expiresAt` et `apiUrl`. Ne prend aucun corps.
`POST {api_url}/v1/twin/{contextId}/embed/refresh-session`	Échange un `refreshToken` (envoyé dans le corps) contre un nouveau `token` et un nouveau `refreshToken`.

Les deux appels utilisent le jeton bearer issu du flux Client Credentials dans l’en-tête Authorization, et tous deux exigent les scopes read:twin et embed:twin sur ce jeton. Sessions d’embed constitue la référence complète de ces deux opérations ; la référence interactive de l’API en publie les schémas.

Étape 2 : Installer le SDK (front-end)

Une fois que votre compte GitHub a obtenu l’accès (voir Prérequis), installez le SDK depuis le registre npm privé GitHub Packages sous le nom @prevu3d/realityconnect-embed. Le README du SDK documente de bout en bout la configuration unique du .npmrc et du Personal Access Token.

Étape 3 : Transmettre la session au SDK

Transmettez les champs de la réponse create-session de votre back-end à votre front-end et associez-les à la configuration du SDK :

Champ `create-session`	Config du SDK	Notes
`iframeUrl`	`iframeUrl`	Une URL de base. Ajoutez vous-même la route d’embed : `${iframeUrl}/embed`. L’ID du jumeau ne figure pas dans l’URL — le jeton de session identifie le jumeau. Voir Construire l’URL de l’iframe.
`apiUrl`	`backendUrl`	Le back-end RealityTwin régional auquel l’embed s’adresse. Ce n’est pas le `{api_url}` appelé à l’étape 1.
`token`	`platformJWT`	Le jeton de session signé avec lequel l’embed s’authentifie. Transmis à l’iframe par le SDK, jamais sous forme de paramètre d’URL.

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

À partir de là, suivez le README du SDK pour installer le package, initialiser le visualiseur et piloter le jumeau.

Étape 4 : Maintenir la session active

Les sessions d’embed sont de courte durée — le token renvoyé par create-session expire aux environs de l’expiresAt qu’il indique. Pour maintenir le jumeau en fonctionnement au-delà de cette fenêtre, rafraîchissez la session depuis votre back-end et transmettez le nouveau jeton d’accès au SDK en cours d’exécution — inutile de recréer l’iframe.

Un schéma courant :

Sur le back-end, exposez un endpoint qui lit le refreshToken stocké pour le jumeau de l’utilisateur courant, appelle refresh-session, persiste le nouveau refreshToken et renvoie le nouveau token (et les autres champs de session) au navigateur.
Sur le front-end, planifiez un rafraîchissement peu avant l’expiration du jeton courant.
Lorsque la nouvelle session arrive, transmettez le nouveau jeton d’accès au SDK en cours d’exécution en appelant twin.updateAccessToken(newAccessToken) :
```
await twin.updateAccessToken(newAccessToken);
```
Le jumeau transmet le nouveau JWT lors de sa prochaine requête back-end — les abonnements ouverts, l’état de la caméra et le workflow chargé sont tous préservés. L’appel renvoie true en cas d’acceptation et false en cas de rejet (également signalé via onError) ; l’appeler avant le déclenchement de onReady lève RealityConnectEmbedError('TWIN_NOT_READY').

La stratégie de planification exacte (minuteur fixe avant l’expiration, à l’activité de l’utilisateur, au changement de visibilité de l’onglet, etc.) dépend de votre application.

Points à connaître

Votre page possède l’interface. L’embed est un visualiseur nu — construisez vos propres contrôles et reliez-les aux commandes du SDK. Consultez l’Introduction pour savoir ce que l’embed inclut et n’inclut pas.
Conservez les identifiants côté serveur. Demandez et rafraîchissez les sessions uniquement depuis votre back-end.
Les sessions expirent. Prévoyez le rafraîchissement du jeton dans le cadre de votre intégration.
Paramètres Enterprise et Sécurité. L’embed ne se charge que lorsqu’il est activé pour votre organisation.

Référence du SDK

Le package @prevu3d/realityconnect-embed constitue la référence complète pour travailler avec le SDK. Lisez son README pour :

La configuration complète du .npmrc et du Personal Access Token pour le registre privé GitHub Packages
La référence de configuration RealityConnectEmbed.init(config)
Les actions et observables d’état de chaque namespace (navigation, objets, POI, POV, utilitaires)
Le flux d’encodage de vue de la caméra pour les liens partageables
Tous les codes d’erreur documentés et les conditions de leur déclenchement
Un bac à sable exécutable que vous pouvez pointer vers un jumeau en direct pour explorer la surface des commandes

Prochaines étapes

Sessions d’embed : les points de terminaison de session, chaque champ de la réponse et la façon de construire l’URL de l’iframe.
Introduction : vue d’ensemble des capacités.
Flux Client Credentials : l’authentification sur laquelle repose ce guide.
Référence interactive de l’API : le catalogue complet de la RealityConnect API.
Exemple en direct sur GitHub : une intégration Vue.js fonctionnelle que vous pouvez copier.
@prevu3d/realityconnect-embed : dépôt des sources