跳转到内容
Prevu3D

快速入门

本指南介绍嵌入 RealityTwin 所需的两项集成：（在您的后端）针对 RealityConnect API 创建嵌入会话，以及（在您的前端）将该会话交给 SDK。所有特定于 SDK 本身的内容——安装细节、初始化、完整的命令与 observable 接口、错误码，以及可运行的 playground——都位于 @prevu3d/realityconnect-embed 包的 README 中，它是权威来源。

前提条件

Section titled “前提条件”

开始之前，请确保您具备：

  • 一个在组织的安全设置中启用了 RealityConnect Embed 的 Enterprise 套餐。
  • 一个使用 Client Credentials 流程的 RealityConnect API OAuth 应用。如果您尚未设置，请先按照 Client Credentials 流程指南操作。
  • 您要嵌入的孪生的 ID。
  • 用于安装 SDK 的账户对私有 prevu3d/realityconnect-embed GitHub 仓库的读取访问权限。访问权限按客户手动授予，需提出请求——请将需要访问权限的 GitHub 用户名提供给您的客户成功经理（CSM），Prevu3D 会将其添加到仓库。GitHub Packages 上的包可见性遵循仓库可见性，因此仅有 read:packages PAT 是不够的——还需要仓库访问权限。

整体如何协作

Section titled “整体如何协作”

在较高层面上，嵌入会话的流程如下：

  1. 您的后端向 RealityConnect API 进行身份验证，并针对特定孪生调用 create-session。API 返回令牌和 URL。
  2. 您的后端将浏览器安全的值（访问令牌、前端 URL 和区域 API URL）转发给您的前端。
  3. 您的前端将这些值传给 SDK，SDK 注入 iframe 并与孪生打开双向通道。
  4. 在当前令牌过期之前，您的后端调用 refresh-session，并将新值交回前端。

您的 OAuth 客户端密钥绝不能到达浏览器——只有您的后端才使用它。

步骤 1：创建嵌入会话（后端）

Section titled “步骤 1：创建嵌入会话（后端）”

嵌入会话管理复用了 RealityConnect API。请完全按照 Client Credentials 流程指南所述，使用 Client Credentials 流程进行身份验证，然后针对孪生调用两个嵌入会话操作：

操作用途
POST {apiUrl}/twin/{twinId}/create-session启动会话。返回 accessToken、refreshToken、frontendUrl 和 apiUrl。
POST {apiUrl}/twin/{twinId}/refresh-session用（在请求体中发送的）refreshToken 换取新的 accessToken 和 refreshToken。

两个调用都在 Authorization 头中使用来自 Client Credentials 流程的 bearer 访问令牌。有关确切的路径和架构，请参阅交互式 API 参考。

步骤 2：安装 SDK（前端）

Section titled “步骤 2：安装 SDK（前端）”

一旦您的 GitHub 账户被授予访问权限（参见前提条件），请从私有的 GitHub Packages npm 注册表中以 @prevu3d/realityconnect-embed 安装 SDK。SDK README 从头到尾记录了一次性的 .npmrc 和 Personal Access Token 设置。

步骤 3：将会话交给 SDK

Section titled “步骤 3：将会话交给 SDK”

将 create-session 响应字段从您的后端转发到前端，并将它们映射到 SDK 的配置：

create-session 字段SDK 配置备注
frontendUrliframeUrl追加嵌入路由和孪生 ID：`${frontendUrl}/embed/${twinId}`。
apiUrlbackendUrl嵌入与之通信的区域 API 基址。
accessTokenplatformJWT嵌入用于身份验证的已签名会话令牌。

从那里开始，请按照 SDK README 来安装该包、初始化查看器并驱动孪生。

步骤 4：保持会话有效

Section titled “步骤 4：保持会话有效”

嵌入会话是短期有效的——create-session 返回的 accessToken 会在一段时间后过期。为了让孪生在该时间窗口之后继续运行，请从您的后端续订会话，并将新的访问令牌交给正在运行的 SDK — 无需重新创建 iframe。

一种常见的模式：

  1. 在后端，公开一个端点，读取为当前用户的孪生存储的 refreshToken，调用 refresh-session，持久化新的 refreshToken，并将新的 accessToken（及其他会话字段）返回给浏览器。

  2. 在前端，安排在当前令牌过期前不久进行一次续订。

  3. 当新会话到达时，通过调用 twin.updateAccessToken(newAccessToken) 将新的访问令牌交给正在运行的 SDK：

    await twin.updateAccessToken(newAccessToken);

    孪生会在下一次后端请求中传递新的 JWT — 已打开的订阅、相机状态和已加载的工作流都会保留。该调用在被接受时返回 true，在被拒绝时返回 false（也会通过 onError 通知）；在 onReady 触发之前调用会抛出 RealityConnectEmbedError('TWIN_NOT_READY')。

确切的调度策略（过期前的固定计时器、在用户活动时、在标签页可见性变化时等）取决于您的应用。

需要注意的事项

Section titled “需要注意的事项”
  • 页面拥有界面。 嵌入是一个裸查看器——请构建您自己的控件并将它们连接到 SDK 命令。有关嵌入包含和不包含的内容，请参阅简介。
  • 将凭据保留在服务器端。 仅从您的后端请求和续订会话。
  • 会话会过期。 请将令牌续订作为集成的一部分加以规划。
  • Enterprise 和安全设置。 仅当为您的组织启用时，嵌入才会加载。

SDK 参考

Section titled “SDK 参考”

@prevu3d/realityconnect-embed 包是使用 SDK 的完整参考。请阅读其 README 以了解：

  • 用于私有 GitHub Packages 注册表的完整 .npmrc 和 Personal Access Token 设置
  • RealityConnectEmbed.init(config) 配置参考
  • 每个命名空间的动作和状态 observable（导航、对象、POI、POV、实用工具）
  • 用于可分享链接的相机视图编码流程
  • 所有已记录的错误码及其触发时机
  • 一个可运行的 playground，您可以将其指向一个在线孪生以探索命令接口

后续步骤

Section titled “后续步骤”