Pular para o conteúdo
Prevu3D

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.

Pré-requisitos

Seção intitulada “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

Seção intitulada “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 access token, a URL do frontend 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)

Seção intitulada “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çãoFinalidade
POST {apiUrl}/twin/{twinId}/create-sessionInicia uma sessão. Retorna accessToken, refreshToken, frontendUrl e apiUrl.
POST {apiUrl}/twin/{twinId}/refresh-sessionTroca um refreshToken (enviado no corpo) por um novo accessToken e refreshToken.

Ambas as chamadas usam o token de acesso bearer do fluxo Client Credentials no cabeçalho Authorization. Consulte a referência interativa da API para conhecer os caminhos e esquemas exatos.

Passo 2: Instalar o SDK (front-end)

Seção intitulada “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

Seção intitulada “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-sessionConfiguração do SDKNotas
frontendUrliframeUrlAcrescente a rota de embed e o ID do gêmeo: `${frontendUrl}/embed/${twinId}`.
apiUrlbackendUrlA base de API regional com a qual o embed se comunica.
accessTokenplatformJWTO token de sessão assinado com o qual o embed se autentica.

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

Seção intitulada “Passo 4: Manter a sessão ativa”

As sessões de embed são de curta duração — o accessToken retornado por create-session expira após um período de tempo. 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 accessToken (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

Seção intitulada “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

Seção intitulada “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

Seção intitulada “Próximos passos”