Sessioni di embed

Una sessione di embed è l’autorizzazione di breve durata che consente a un RealityTwin di essere renderizzato all’interno della tua pagina. Il tuo backend ne crea una tramite la RealityConnect API, inoltra al tuo front-end i valori sicuri per il browser e il tuo front-end li passa all’SDK. Questa pagina è il riferimento per quei due endpoint, per ogni campo che restituiscono e per l’unico valore che devi comporre tu: l’URL dell’iframe.

---

I due endpoint di sessione

Entrambe le operazioni risiedono sul contesto del gemello e sono pubblicate nel riferimento interattivo dell’API, contrassegnate come sperimentali.

Metodo	Percorso	Corpo
GET	{api_url}/v1/twin/{contextId}/embed/create-session	Nessuno
POST	{api_url}/v1/twin/{contextId}/embed/refresh-session	{ "refreshToken": "<base64 refresh token>" }

{api_url} è la base regionale della tua API, che termina già con /realityconnect-api. Una chiamata completa ha quindi questo aspetto:

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

{contextId} è l’ID del gemello che vuoi incorporare. RealityPlan non è supportato qui.

Attenzione

Crea e rinnova le sessioni dal tuo backend. Il tuo client secret OAuth e il refresh token non devono mai raggiungere il browser.

Scope richiesti

Entrambe le operazioni richiedono due scope sullo stesso access token:

Scope	Perché
read:twin	Leggere il gemello a cui punta la sessione
embed:twin	Generare una sessione di embed per esso

Un token che ne possiede uno solo dei due riceve 403 Forbidden con Insufficient OAuth scopes. Aggiungili entrambi alla tua applicazione OAuth prima di iniziare; consulta la guida Flusso Client Credentials.

Le sessioni di embed utilizzano inoltre un budget di rate limit dedicato e più stretto rispetto al resto dell’API: crea quindi una sessione per ogni sessione di visualizzazione, anziché a ogni rendering della pagina.

La risposta di 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	Che cos’è	Configurazione dell’SDK
iframeUrl	L’URL di base del visualizzatore di embed. Completalo prima dell’uso: consulta Costruire l’URL dell’iframe.	iframeUrl, dopo che hai aggiunto la route di embed
token	Il JWT di sessione firmato. L’SDK lo richiede; il gemello incorporato si autentica con esso.	platformJWT
refreshToken	Segreto in base64 abbinato a questa sessione. Conservalo sul tuo backend.	—
expiresAt	Timestamp ISO 8601 entro cui rinnovare la sessione: qualche minuto prima che token stesso smetta di essere accettato.	—
apiUrl	Il backend regionale di RealityTwin con cui comunica il gemello incorporato (…/reality-twin). Non è l’{api_url} che hai chiamato sopra: gli endpoint di sessione non risiedono su di esso.	backendUrl

refresh-session restituisce la stessa struttura senza iframeUrl e apiUrl. Questi due valori ti servono una sola volta: iframeUrl è costante per l’ambiente e apiUrl è costante per la regione della tua organizzazione.

Nota

expiresAt è una stima volutamente prudente, calcolata al momento della costruzione della risposta, e cade qualche minuto prima della scadenza effettiva del token. Consideralo il momento in cui rinnovare, non l’istante esatto in cui il token cessa di essere valido.

Costruire l’URL dell’iframe

iframeUrl è un URL di base, non un src già pronto. È la stessa costante per ogni gemello all’interno di un ambiente: in produzione, https://embed.prevu3d.com/reality-twin. Aggiungici la route di embed:

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

L’ID del gemello non è necessario nell’URL — il token di sessione identifica già il gemello e il visualizzatore lo legge da lì.

Uniscili con una sola barra: iframeUrl non termina con una barra, quindi `${iframeUrl}/embed` è corretto.

Passa l’URL completo all’SDK:

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

Attenzione

Passare iframeUrl senza modificarlo non carica affatto il visualizzatore del gemello. Il valore non termina con una barra e, sull’host di embed, quel percorso esatto è servito da un’applicazione diversa: solo i percorsi sottostanti raggiungono il visualizzatore. L’handshake dell’SDK non ha quindi alcun interlocutore, perciò onReady non viene mai richiamato e l’SDK segnala TWIN_TIMEOUT una volta scaduto il suo timeout di attesa.

Il token non viaggia mai nell’URL

Il JWT di sessione raggiunge l’iframe tramite l’handshake postMessage INIT_CONFIG dell’SDK, come valore di configurazione platformJWT. Non aggiungerlo all’URL dell’iframe come parametro di query: il gemello incorporato non ne legge alcuno e inserire una credenziale attiva in un URL la espone alla cronologia del browser, alle intestazioni referrer e ai log del server.

Per lo stesso motivo, la pagina di embed è pensata per essere eseguita all’interno dell’iframe dell’SDK. Incollare un URL completo in una scheda del browser, da solo, non caricherà alcun gemello, perché non c’è nulla che gli fornisca il token e l’URL del backend.

Mantenere attiva la sessione

Le sessioni sono di breve durata. Prima di expiresAt, chiama refresh-session dal tuo backend con il refreshToken memorizzato, rendi persistente quello nuovo e passa il nuovo token all’SDK in esecuzione con twin.updateAccessToken(newAccessToken): non è necessario ricreare l’iframe. Consulta il Passaggio 4 di Per iniziare per lo schema completo.

Prossimi passi

• Per iniziare: l’integrazione end-to-end che questo riferimento supporta.
• Flusso Client Credentials: come ottenere l’access token necessario a queste chiamate.
• Riferimento interattivo dell’API: lo schema pubblicato di entrambe le operazioni.