Salta ai contenuti
Prevu3D

Per iniziare

Questa guida illustra le due integrazioni necessarie per incorporare un RealityTwin: creare una sessione di embed sulla RealityConnect API (dal tuo backend) e passare quella sessione all’SDK (nel tuo front-end). Tutto ciò che è specifico dell’SDK stesso — dettagli di installazione, inizializzazione, la superficie completa di comandi e observable, i codici di errore e il playground eseguibile — si trova nel README del pacchetto @prevu3d/realityconnect-embed, che è la fonte di riferimento.

Prerequisiti

Sezione intitolata “Prerequisiti”

Prima di iniziare, assicurati di avere:

  • Un piano Enterprise con RealityConnect Embed abilitato nelle impostazioni di Sicurezza della tua organizzazione.
  • Un’applicazione OAuth di RealityConnect API che utilizza il flusso Client Credentials. Se non ne hai ancora configurata una, segui prima la guida Flusso Client Credentials.
  • L’ID del gemello che desideri incorporare.
  • Accesso in lettura al repository GitHub privato prevu3d/realityconnect-embed per l’account che installerà l’SDK. L’accesso viene concesso manualmente per cliente su richiesta: contatta il tuo Customer Success Manager (CSM) con i nomi utente GitHub che necessitano dell’accesso e Prevu3D li aggiungerà al repository. La visibilità del pacchetto su GitHub Packages segue la visibilità del repository, quindi un PAT read:packages da solo non è sufficiente: è richiesto anche l’accesso al repository.

Come tutto si combina

Sezione intitolata “Come tutto si combina”

Ad alto livello, una sessione di embed procede così:

  1. Il tuo backend si autentica presso la RealityConnect API e chiama create-session per un gemello specifico. L’API restituisce token e URL.
  2. Il tuo backend inoltra i valori sicuri per il browser (l’access token, l’URL del frontend e l’URL regionale dell’API) al tuo front-end.
  3. Il tuo front-end passa quei valori all’SDK, che inietta l’iframe e apre un canale bidirezionale con il gemello.
  4. Prima che il token corrente scada, il tuo backend chiama refresh-session e restituisce i valori nuovi al front-end.

Il tuo client secret OAuth non deve mai raggiungere il browser: solo il tuo backend lo utilizza.

Passaggio 1: Creare una sessione di embed (backend)

Sezione intitolata “Passaggio 1: Creare una sessione di embed (backend)”

La gestione delle sessioni di embed riutilizza la RealityConnect API. Autenticati con il flusso Client Credentials esattamente come descritto nella guida Flusso Client Credentials, quindi chiama le due operazioni di sessione di embed sul gemello:

OperazioneScopo
POST {apiUrl}/twin/{twinId}/create-sessionAvvia una sessione. Restituisce accessToken, refreshToken, frontendUrl e apiUrl.
POST {apiUrl}/twin/{twinId}/refresh-sessionScambia un refreshToken (inviato nel corpo) con un nuovo accessToken e refreshToken.

Entrambe le chiamate utilizzano il token di accesso bearer del flusso Client Credentials nell’intestazione Authorization. Consulta il riferimento interattivo dell’API per i percorsi e gli schemi esatti.

Passaggio 2: Installare l’SDK (front-end)

Sezione intitolata “Passaggio 2: Installare l’SDK (front-end)”

Una volta che al tuo account GitHub è stato concesso l’accesso (consulta Prerequisiti), installa l’SDK dal registro npm privato di GitHub Packages come @prevu3d/realityconnect-embed. Il README dell’SDK documenta dall’inizio alla fine la configurazione una tantum del .npmrc e del Personal Access Token.

Passaggio 3: Passare la sessione all’SDK

Sezione intitolata “Passaggio 3: Passare la sessione all’SDK”

Inoltra i campi della risposta di create-session dal tuo backend al tuo front-end e mappali sulla configurazione dell’SDK:

Campo di create-sessionConfigurazione dell’SDKNote
frontendUrliframeUrlAggiungi la route di embed e l’ID del gemello: `${frontendUrl}/embed/${twinId}`.
apiUrlbackendUrlLa base API regionale con cui comunica l’embed.
accessTokenplatformJWTIl token di sessione firmato con cui l’embed si autentica.

Da lì, segui il README dell’SDK per installare il pacchetto, inizializzare il visualizzatore e pilotare il gemello.

Passaggio 4: Mantenere attiva la sessione

Sezione intitolata “Passaggio 4: Mantenere attiva la sessione”

Le sessioni di embed sono di breve durata: l’accessToken restituito da create-session scade dopo un certo periodo di tempo. Per mantenere il gemello in funzione oltre quella finestra, rinnova la sessione dal tuo backend e consegna il nuovo token di accesso all’SDK in esecuzione — non è necessario ricreare l’iframe.

Uno schema comune:

  1. Sul backend, esponi un endpoint che legga il refreshToken memorizzato per il gemello dell’utente corrente, chiami refresh-session, renda persistente il nuovo refreshToken e restituisca il nuovo accessToken (e gli altri campi della sessione) al browser.

  2. Sul front-end, pianifica un rinnovo poco prima che il token corrente scada.

  3. Quando arriva la nuova sessione, consegna il nuovo token di accesso all’SDK in esecuzione chiamando twin.updateAccessToken(newAccessToken):

    await twin.updateAccessToken(newAccessToken);

    Il gemello incorpora il nuovo JWT nella sua prossima richiesta al backend — le sottoscrizioni aperte, lo stato della telecamera e il workflow caricato vengono tutti preservati. La chiamata si risolve con true in caso di accettazione e con false in caso di rifiuto (segnalato anche tramite onError); chiamarla prima che onReady venga attivato genera RealityConnectEmbedError('TWIN_NOT_READY').

L’esatta strategia di pianificazione (timer fisso prima della scadenza, all’attività dell’utente, al cambio di visibilità della scheda, ecc.) dipende dalla tua applicazione.

Aspetti da tenere presente

Sezione intitolata “Aspetti da tenere presente”
  • La tua pagina possiede l’interfaccia. L’embed è un visualizzatore essenziale: crea i tuoi controlli e collegali ai comandi dell’SDK. Consulta l’Introduzione per sapere cosa include e cosa non include l’embed.
  • Mantieni le credenziali lato server. Richiedi e rinnova le sessioni solo dal tuo backend.
  • Le sessioni scadono. Prevedi il rinnovo del token come parte della tua integrazione.
  • Impostazioni Enterprise e Sicurezza. L’embed viene caricato solo quando è abilitato per la tua organizzazione.

Riferimento SDK

Sezione intitolata “Riferimento SDK”

Il pacchetto @prevu3d/realityconnect-embed è il riferimento completo per lavorare con l’SDK. Leggi il suo README per:

  • La configurazione completa del .npmrc e del Personal Access Token per il registro privato GitHub Packages
  • Il riferimento di configurazione RealityConnectEmbed.init(config)
  • Le azioni e gli observable di stato di ogni namespace (navigazione, oggetti, POI, POV, utilità)
  • Il flusso di codifica delle viste della camera per i link condivisibili
  • Tutti i codici di errore documentati e quando si attivano
  • Un playground eseguibile che puoi puntare a un gemello dal vivo per esplorare la superficie dei comandi

Prossimi passi

Sezione intitolata “Prossimi passi”