Sessões de Embed

Uma sessão de embed é a autorização de curta duração que permite renderizar um RealityTwin dentro da sua página. Seu backend cria uma pela RealityConnect API, encaminha ao seu front-end os valores seguros para o navegador, e o seu front-end os entrega ao SDK. Esta página é a referência desses dois endpoints, de cada campo que eles retornam e do único valor que você mesmo precisa montar: a URL do iframe.

---

Os dois endpoints de sessão

Ambas as operações ficam no contexto do gêmeo e estão publicadas na referência interativa da API, marcadas como experimentais.

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

{api_url} é a base regional da sua API, que já termina em /realityconnect-api. Portanto, uma chamada completa fica assim:

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

{contextId} é o ID do gêmeo que você quer incorporar. O RealityPlan não é compatível aqui.

Cuidado

Crie e renove as sessões a partir do seu próprio backend. Seu client secret do OAuth e o refresh token nunca devem chegar ao navegador.

Escopos necessários

Ambas as operações exigem dois escopos no mesmo token de acesso:

Escopo	Por quê
read:twin	Ler o gêmeo que a sessão tem como alvo
embed:twin	Emitir uma sessão de embed para ele

Um token que tenha apenas um dos dois recebe 403 Forbidden com Insufficient OAuth scopes. Adicione ambos ao seu aplicativo OAuth antes de começar; consulte o guia Fluxo Client Credentials.

As sessões de embed também usam um orçamento de limite de taxa dedicado e mais restrito que o do restante da API, portanto crie uma sessão por sessão de visualização, e não a cada renderização de página.

A resposta 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	O que é	Configuração do SDK
iframeUrl	A URL base do visualizador de embed. Complete-a antes de usá-la — consulte Construindo a URL do iframe.	iframeUrl, depois de você acrescentar a rota de embed
token	O JWT de sessão assinado. O SDK o exige; o gêmeo incorporado se autentica com ele.	platformJWT
refreshToken	Segredo em Base64 associado a esta sessão. Mantenha-o no seu backend.	—
expiresAt	Carimbo de data/hora em ISO 8601 até o qual você deve renovar a sessão — alguns minutos antes de o próprio token deixar de ser aceito.	—
apiUrl	O backend regional do RealityTwin com o qual o gêmeo incorporado se comunica (…/reality-twin). Não é o {api_url} que você chamou acima — os endpoints de sessão não ficam nele.	backendUrl

refresh-session retorna o mesmo formato sem iframeUrl e sem apiUrl. Você só precisa desses dois uma vez: iframeUrl é constante dentro do ambiente e apiUrl é constante para a região da sua organização.

Nota

expiresAt é uma estimativa deliberadamente conservadora, calculada no momento em que a resposta é montada, e cai alguns minutos antes da expiração do próprio token. Trate-o como o momento de renovar, não como o instante exato em que o token deixa de ser aceito.

Construindo a URL do iframe

iframeUrl é uma URL base, não um src pronto. É a mesma constante para todos os gêmeos dentro de um ambiente — em produção, https://embed.prevu3d.com/reality-twin. Acrescente a rota de embed a ela:

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

O ID do gêmeo não é necessário na URL — o token de sessão já identifica o gêmeo, e o visualizador o lê a partir dele.

Junte os dois com exatamente uma barra: iframeUrl não termina em barra, portanto `${iframeUrl}/embed` está correto.

Entregue a URL completa ao SDK:

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

Cuidado

Repassar iframeUrl sem alterações não carrega o visualizador do gêmeo de forma alguma. O valor não termina em barra e, no host de embed, esse caminho exato é servido por um aplicativo diferente — apenas os caminhos abaixo dele chegam ao visualizador. O handshake do SDK então não tem com quem se comunicar, portanto onReady nunca é disparado e o SDK reporta TWIN_TIMEOUT assim que o seu tempo limite de prontidão se esgota.

O token nunca vai na URL

O JWT de sessão chega ao iframe pelo handshake postMessage INIT_CONFIG do SDK, como o valor de configuração platformJWT. Não o acrescente à URL do iframe como parâmetro de consulta — o gêmeo incorporado não lê nenhum, e colocar uma credencial ativa em uma URL a expõe ao histórico do navegador, aos cabeçalhos de referrer e aos logs do servidor.

Pelo mesmo motivo, a página de embed espera ser executada dentro do iframe do SDK. Colar uma URL completa em uma aba do navegador, por si só, não carrega um gêmeo, porque não há nada ali para lhe entregar o token e a URL do backend.

Mantendo a sessão ativa

As sessões são de curta duração. Antes de expiresAt, chame refresh-session a partir do seu backend com o refreshToken armazenado, persista o novo e passe o novo token ao SDK em execução com twin.updateAccessToken(newAccessToken) — não é necessário recriar o iframe. Consulte o Passo 4 de Primeiros passos para o padrão completo.

Próximos passos

• Primeiros passos: a integração de ponta a ponta que esta referência apoia.
• Fluxo Client Credentials: como obter o token de acesso que estas chamadas exigem.
• Referência interativa da API: o esquema publicado das duas operações.