Primeiros passos

Este guia percorre as duas integrações necessárias para incorporar um RealityTwin: criar uma sessão de embed na RealityConnect API (a partir do seu backend) e entregar essa sessão ao SDK (no seu front-end). Tudo o que é específico do próprio SDK — detalhes de instalação, inicialização, a superfície completa de comandos e observáveis, códigos de erro e o playground executável — está no README do pacote @prevu3d/realityconnect-embed, que é a fonte de referência.

Dica

Uma integração completa em Vue.js está implantada em rcembed-example.prevu3d.io e seu código-fonte está no GitHub em prevu3d/realityconnect-embed-example. Se preferir copiar uma configuração funcional em vez de criar uma do zero, comece por aí. O repositório do GitHub é apenas por convite — peça ao seu Customer Success Manager para adicionar a sua conta do GitHub, da mesma forma como o acesso ao repositório do SDK é concedido.

---

Pré-requisitos

Antes de começar, certifique-se de ter:

• Um plano Enterprise com o RealityConnect Embed habilitado nas configurações de Segurança da sua organização.
• Uma aplicação OAuth da RealityConnect API usando o fluxo Client Credentials. Se ainda não configurou uma, siga primeiro o guia Fluxo Client Credentials.
• O ID do gêmeo que você deseja incorporar.
• Acesso de leitura ao repositório privado do GitHub prevu3d/realityconnect-embed para a conta que instalará o SDK. O acesso é concedido manualmente por cliente mediante solicitação — entre em contato com o seu Customer Success Manager (CSM) com os nomes de usuário do GitHub que precisam de acesso, e a Prevu3D os adicionará ao repositório. A visibilidade do pacote no GitHub Packages segue a visibilidade do repositório, portanto um PAT read:packages sozinho não é suficiente — o acesso ao repositório também é necessário.

Como tudo se encaixa

Em alto nível, uma sessão de embed flui assim:

1. Seu backend autentica-se junto à RealityConnect API e chama create-session para um gêmeo específico. A API retorna tokens e URLs.
2. Seu backend encaminha os valores seguros para o navegador (o token de sessão, a URL base do iframe e a URL regional da API) ao seu front-end.
3. Seu front-end passa esses valores ao SDK, que injeta o iframe e abre um canal bidirecional com o gêmeo.
4. Antes de o token atual expirar, seu backend chama refresh-session e devolve os valores novos ao front-end.

Seu client secret do OAuth nunca deve chegar ao navegador — somente o seu backend o utiliza.

Passo 1: Criar uma sessão de embed (backend)

O gerenciamento de sessões de embed reutiliza a RealityConnect API. Autentique-se com o fluxo Client Credentials exatamente como descrito no guia Fluxo Client Credentials e, em seguida, chame as duas operações de sessão de embed no gêmeo:

Operação	Finalidade
GET {api_url}/v1/twin/{contextId}/embed/create-session	Inicia uma sessão. Retorna iframeUrl, token, refreshToken, expiresAt e apiUrl. Não recebe corpo.
POST {api_url}/v1/twin/{contextId}/embed/refresh-session	Troca um refreshToken (enviado no corpo) por um novo token e refreshToken.

Ambas as chamadas usam o token de acesso bearer do fluxo Client Credentials no cabeçalho Authorization, e ambas exigem os escopos read:twin e embed:twin nesse token. Sessões de Embed é a referência completa dessas duas operações; a referência interativa da API publica os esquemas delas.

Cuidado

Solicite e renove sempre as sessões de embed a partir do seu próprio backend. Seu client secret do OAuth e seus access tokens nunca devem chegar ao navegador. O navegador recebe apenas os valores que o seu backend escolher encaminhar a ele.

Passo 2: Instalar o SDK (front-end)

Assim que a sua conta do GitHub tiver o acesso concedido (consulte Pré-requisitos), instale o SDK a partir do registro npm privado do GitHub Packages como @prevu3d/realityconnect-embed. O README do SDK documenta de ponta a ponta a configuração única do .npmrc e do Personal Access Token.

Passo 3: Entregar a sessão ao SDK

Encaminhe os campos da resposta de create-session do seu backend ao seu front-end e mapeie-os para a configuração do SDK:

Campo de create-session	Configuração do SDK	Notas
iframeUrl	iframeUrl	Uma URL base. Acrescente você mesmo a rota de embed: `${iframeUrl}/embed`. O ID do gêmeo não vai na URL — o token de sessão identifica o gêmeo. Consulte Construindo a URL do iframe.
apiUrl	backendUrl	O backend regional do RealityTwin com o qual o embed se comunica. Não é o {api_url} que você chamou no Passo 1.
token	platformJWT	O token de sessão assinado com o qual o embed se autentica. Entregue ao iframe pelo SDK, nunca como parâmetro de URL.

Cuidado

iframeUrl é uma URL base, não um src de iframe. `${iframeUrl}/embed` é o valor de que o SDK precisa — nada acrescenta a rota de embed por você.

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

A partir daí, siga o README do SDK para instalar o pacote, inicializar o visualizador e controlar o gêmeo.

Passo 4: Manter a sessão ativa

As sessões de embed são de curta duração — o token retornado por create-session expira aproximadamente no expiresAt que ele informa. Para manter o gêmeo em funcionamento além dessa janela, renove a sessão a partir do seu backend e entregue o novo token de acesso ao SDK em execução — não é necessário recriar o iframe.

Um padrão comum:

1. No backend, exponha um endpoint que leia o refreshToken armazenado para o gêmeo do usuário atual, chame refresh-session, persista o novo refreshToken e retorne o novo token (e os demais campos da sessão) ao navegador.

2. No front-end, agende uma renovação pouco antes de o token atual expirar.

3. Quando a nova sessão chegar, entregue o novo token de acesso ao SDK em execução chamando twin.updateAccessToken(newAccessToken):

   await twin.updateAccessToken(newAccessToken);

   O gêmeo incorpora o novo JWT na sua próxima solicitação ao backend — as assinaturas abertas, o estado da câmera e o fluxo de trabalho carregado são preservados. A chamada resolve para true em caso de aceitação e para false em caso de rejeição (também sinalizada via onError); chamá-la antes de onReady ser disparado lança RealityConnectEmbedError('TWIN_NOT_READY').

A estratégia exata de agendamento (temporizador fixo antes da expiração, na atividade do usuário, na mudança de visibilidade da aba, etc.) depende da sua aplicação.

Aspectos a ter em conta

• Sua página possui a interface. O embed é um visualizador básico — crie seus próprios controles e conecte-os aos comandos do SDK. Consulte a Introdução para saber o que o embed inclui e o que não inclui.
• Mantenha as credenciais no servidor. Solicite e renove as sessões apenas a partir do seu backend.
• As sessões expiram. Planeje a renovação do token como parte da sua integração.
• Configurações de Enterprise e Segurança. O embed só é carregado quando está habilitado para a sua organização.

Referência do SDK

O pacote @prevu3d/realityconnect-embed é a referência completa para trabalhar com o SDK. Leia o README dele para:

• A configuração completa do .npmrc e do Personal Access Token para o registro privado do GitHub Packages
• A referência de configuração RealityConnectEmbed.init(config)
• As ações e os observáveis de estado de cada namespace (navegação, objetos, POI, POV, utilitários)
• O fluxo de codificação de vistas da câmera para links compartilháveis
• Todos os códigos de erro documentados e quando são disparados
• Um playground executável que você pode apontar para um gêmeo ao vivo a fim de explorar a superfície de comandos

Próximos passos

• Sessões de Embed: os endpoints de sessão, cada campo da resposta e como montar a URL do iframe.
• Introdução: visão geral das capacidades.
• Fluxo Client Credentials: a autenticação sobre a qual este guia se baseia.
• Referência interativa da API: o catálogo completo da RealityConnect API.
• Exemplo ao vivo no GitHub: uma integração funcional em Vue.js que você pode copiar.
• @prevu3d/realityconnect-embed: repositório de fontes