Primeros pasos

Esta guía recorre las dos integraciones que necesita para incrustar un RealityTwin: crear una sesión de embed contra la RealityConnect API (desde su backend) y entregar esa sesión al SDK (en su front-end). Todo lo específico del propio SDK (detalles de instalación, inicialización, la superficie completa de comandos y observables, códigos de error y el playground ejecutable) se encuentra en el README del paquete @prevu3d/realityconnect-embed, que es la fuente de referencia.

Requisitos previos

Antes de empezar, asegúrese de disponer de:

Un plan Enterprise con RealityConnect Embed habilitado en los ajustes de Seguridad de su organización.
Una aplicación OAuth de RealityConnect API que use el flujo de Client Credentials. Si aún no ha configurado una, siga primero la guía Flujo de Client Credentials.
El ID del gemelo que desea incrustar.
Acceso de lectura al repositorio privado de GitHub prevu3d/realityconnect-embed para la cuenta que instalará el SDK. El acceso se concede manualmente por cliente a petición: póngase en contacto con su Customer Success Manager (CSM) con los nombres de usuario de GitHub que necesitan acceso, y Prevu3D los añadirá al repositorio. La visibilidad del paquete en GitHub Packages sigue la visibilidad del repositorio, por lo que un PAT read:packages por sí solo no basta: también se requiere acceso al repositorio.

Cómo encaja todo

A alto nivel, una sesión de embed fluye así:

Su backend se autentica ante la RealityConnect API y llama a create-session para un gemelo específico. La API devuelve tokens y URL.
Su backend reenvía los valores seguros para el navegador (el access token, la URL del frontend y la URL regional de la API) a su front-end.
Su front-end pasa esos valores al SDK, que inyecta el iframe y abre un canal bidireccional con el gemelo.
Antes de que caduque el token actual, su backend llama a refresh-session y devuelve los valores nuevos al front-end.

Su client secret de OAuth nunca debe llegar al navegador; solo lo usa su backend.

Paso 1: Crear una sesión de embed (backend)

La gestión de sesiones de embed reutiliza la RealityConnect API. Autentíquese con el flujo de Client Credentials exactamente como se describe en la guía Flujo de Client Credentials y, a continuación, llame a las dos operaciones de sesión de embed sobre el gemelo:

Operación	Propósito
`POST {apiUrl}/twin/{twinId}/create-session`	Inicia una sesión. Devuelve `accessToken`, `refreshToken`, `frontendUrl` y `apiUrl`.
`POST {apiUrl}/twin/{twinId}/refresh-session`	Intercambia un `refreshToken` (enviado en el cuerpo) por un nuevo `accessToken` y `refreshToken`.

Ambas llamadas usan el token de acceso bearer del flujo de Client Credentials en la cabecera Authorization. Consulte la referencia interactiva de la API para conocer las rutas y los esquemas exactos.

Paso 2: Instalar el SDK (front-end)

Una vez que su cuenta de GitHub tenga acceso concedido (consulte Requisitos previos), instale el SDK desde el registro npm privado de GitHub Packages como @prevu3d/realityconnect-embed. El README del SDK documenta de principio a fin la configuración única del .npmrc y del Personal Access Token.

Paso 3: Entregar la sesión al SDK

Reenvíe los campos de la respuesta de create-session desde su backend a su front-end y asígnelos a la configuración del SDK:

Campo de `create-session`	Configuración del SDK	Notas
`frontendUrl`	`iframeUrl`	Añada la ruta de embed y el ID del gemelo: `${frontendUrl}/embed/${twinId}`.
`apiUrl`	`backendUrl`	La base de API regional con la que se comunica el embed.
`accessToken`	`platformJWT`	El token de sesión firmado con el que se autentica el embed.

A partir de ahí, siga el README del SDK para instalar el paquete, inicializar el visor y controlar el gemelo.

Paso 4: Mantener la sesión activa

Las sesiones de embed son de corta duración: el accessToken que devuelve create-session caduca tras un periodo de tiempo. Para mantener el gemelo en funcionamiento más allá de esa ventana, renueve la sesión desde su backend y entregue el nuevo token de acceso al SDK en ejecución — no es necesario volver a crear el iframe.

Un patrón común:

En el backend, exponga un endpoint que lea el refreshToken almacenado para el gemelo del usuario actual, llame a refresh-session, persista el nuevo refreshToken y devuelva el nuevo accessToken (y los demás campos de la sesión) al navegador.
En el front-end, programe una renovación poco antes de que caduque el token actual.
Cuando llegue la sesión nueva, entregue el nuevo token de acceso al SDK en ejecución llamando a twin.updateAccessToken(newAccessToken):
```
await twin.updateAccessToken(newAccessToken);
```
El gemelo incorpora el nuevo JWT en su siguiente solicitud al backend — las suscripciones abiertas, el estado de la cámara y el flujo de trabajo cargado se mantienen. La llamada se resuelve con true en caso de aceptación y con false en caso de rechazo (también notificado mediante onError); llamarla antes de que se dispare onReady lanza RealityConnectEmbedError('TWIN_NOT_READY').

La estrategia exacta de programación (temporizador fijo antes de la caducidad, según la actividad del usuario, al cambiar la visibilidad de la pestaña, etc.) depende de su aplicación.

Aspectos a tener en cuenta

Su página posee la interfaz. El embed es un visor básico: cree sus propios controles y conéctelos a los comandos del SDK. Consulte la Introducción para saber qué incluye y qué no incluye el embed.
Mantenga las credenciales en el servidor. Solicite y renueve las sesiones solo desde su backend.
Las sesiones caducan. Prevea la renovación del token como parte de su integración.
Ajustes de Enterprise y Seguridad. El embed solo se carga cuando está habilitado para su organización.

Referencia del SDK

El paquete @prevu3d/realityconnect-embed es la referencia completa para trabajar con el SDK. Lea su README para conocer:

La configuración completa del .npmrc y del Personal Access Token para el registro privado de GitHub Packages
La referencia de configuración RealityConnectEmbed.init(config)
Las acciones y los observables de estado de cada namespace (navegación, objetos, POI, POV, utilidades)
El flujo de codificación de vistas de la cámara para enlaces compartibles
Todos los códigos de error documentados y cuándo se activan
Un playground ejecutable que puede apuntar a un gemelo en vivo para explorar la superficie de comandos

Próximos pasos

Introducción: descripción general de las capacidades.
Flujo de Client Credentials: la autenticación sobre la que se basa esta guía.
Referencia interactiva de la API: el catálogo completo de la RealityConnect API.
Ejemplo en vivo en GitHub: una integración funcional de Vue.js que puede copiar.
@prevu3d/realityconnect-embed: repositorio de fuentes