Sesiones de embed

Una sesión de embed es la autorización de corta duración que permite que un RealityTwin se renderice dentro de su página. Su backend crea una a través de la RealityConnect API, reenvía a su front-end los valores seguros para el navegador y su front-end los entrega al SDK. Esta página es la referencia de esos dos endpoints, de cada campo que devuelven y del único valor que debe componer usted mismo: la URL del iframe.

---

Los dos endpoints de sesión

Ambas operaciones se sitúan sobre el contexto del gemelo y están publicadas en la referencia interactiva de la API, marcadas como experimentales.

Método	Ruta	Cuerpo
GET	{api_url}/v1/twin/{contextId}/embed/create-session	Ninguno
POST	{api_url}/v1/twin/{contextId}/embed/refresh-session	{ "refreshToken": "<base64 refresh token>" }

{api_url} es la base regional de su API, que ya termina en /realityconnect-api. Por tanto, una llamada completa tiene este aspecto:

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

{contextId} es el ID del gemelo que quiere incrustar. RealityPlan no se admite aquí.

Precaución

Cree y renueve las sesiones desde su propio backend. Su client secret de OAuth y el refresh token nunca deben llegar al navegador.

Ámbitos requeridos

Ambas operaciones requieren dos ámbitos en el mismo access token:

Ámbito	Por qué
read:twin	Leer el gemelo al que apunta la sesión
embed:twin	Emitir una sesión de embed para él

Un token que solo tenga uno de los dos recibe 403 Forbidden con Insufficient OAuth scopes. Añada ambos a su aplicación OAuth antes de empezar; consulte la guía Flujo de Client Credentials.

Las sesiones de embed usan además un presupuesto de límite de peticiones propio y más estricto que el del resto de la API, así que cree una sesión por sesión de visualización y no por cada renderizado de la página.

La respuesta 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"
}

Campo	Qué es	Configuración del SDK
iframeUrl	La URL base del visor de embed. Complétela antes de usarla; consulte Construir la URL del iframe.	iframeUrl, después de añadir la ruta de embed
token	El JWT de sesión firmado. El SDK lo requiere; el gemelo incrustado se autentica con él.	platformJWT
refreshToken	Secreto en base64 asociado a esta sesión. Consérvelo en su backend.	—
expiresAt	Marca de tiempo ISO 8601 antes de la cual debe renovar la sesión — unos minutos antes de que el propio token deje de aceptarse.	—
apiUrl	El backend regional de RealityTwin con el que se comunica el gemelo incrustado (…/reality-twin). No es el {api_url} al que ha llamado más arriba — los endpoints de sesión no residen en él.	backendUrl

refresh-session devuelve la misma estructura sin iframeUrl ni apiUrl. Solo necesita esos dos valores una vez: iframeUrl es constante para el entorno y apiUrl es constante para la región de su organización.

Nota

expiresAt es una estimación deliberadamente conservadora que se calcula al construir la respuesta y se sitúa unos minutos antes de la caducidad propia del token. Considérelo el momento de renovar, no el instante exacto en que el token deja de ser válido.

Construir la URL del iframe

iframeUrl es una URL base, no un src terminado. Es la misma constante para todos los gemelos dentro de un entorno; en producción, https://embed.prevu3d.com/reality-twin. Añádale la ruta de embed:

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

El ID del gemelo no es necesario en la URL — el token de sesión ya identifica al gemelo y el visor lo lee de ahí.

Junte ambas partes con exactamente una barra: iframeUrl no termina en barra, así que `${iframeUrl}/embed` es correcto.

Entregue la URL ya completa al SDK:

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

Precaución

Transmitir iframeUrl sin cambios no carga en absoluto el visor del gemelo. El valor no termina en barra y, en el host de embed, esa ruta exacta la sirve una aplicación distinta: solo las rutas por debajo de ella llegan al visor. El handshake del SDK no tiene entonces con qué comunicarse, así que onReady nunca se dispara y el SDK informa de TWIN_TIMEOUT en cuanto transcurre su tiempo de espera de preparación.

El token nunca viaja en la URL

El JWT de sesión llega al iframe a través del handshake postMessage INIT_CONFIG del SDK, como valor de configuración platformJWT. No lo añada a la URL del iframe como parámetro de consulta: el gemelo incrustado no lee ninguno, y colocar una credencial activa en una URL la expone al historial del navegador, a las cabeceras referrer y a los registros del servidor.

Por el mismo motivo, la página del embed está pensada para ejecutarse dentro del iframe del SDK. Pegar por sí sola una URL ya completa en una pestaña del navegador no carga ningún gemelo, porque no hay nada que le entregue el token ni la URL del backend.

Mantener la sesión activa

Las sesiones son de corta duración. Antes de expiresAt, llame a refresh-session desde su backend con el refreshToken almacenado, persista el nuevo y pase el nuevo token al SDK en ejecución con twin.updateAccessToken(newAccessToken): no es necesario volver a crear el iframe. Consulte el Paso 4 de Primeros pasos para conocer el patrón completo.

Próximos pasos

• Primeros pasos: la integración de principio a fin sobre la que se apoya esta referencia.
• Flujo de Client Credentials: cómo obtener el access token que necesitan estas llamadas.
• Referencia interactiva de la API: el esquema publicado de ambas operaciones.