跳转到内容
Prevu3D

嵌入会话

嵌入会话是让 RealityTwin 在您的页面中渲染的短期授权。您的后端通过 RealityConnect API 创建会话，将浏览器安全的值转发给您的前端，再由您的前端将它们交给 SDK。本页是这两个端点的参考，涵盖它们返回的每一个字段，以及您必须自行拼装的那一个值：iframe URL。

两个会话端点

Section titled “两个会话端点”

这两个操作都位于孪生上下文之上，并已发布在交互式 API 参考中，标记为实验性。

方法路径请求体
GET{api_url}/v1/twin/{contextId}/embed/create-session无
POST{api_url}/v1/twin/{contextId}/embed/refresh-session{ "refreshToken": "<base64 refresh token>" }

{api_url} 是您的区域 API 基址，其结尾已包含 /realityconnect-api。因此一次完整的调用如下所示：

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

{contextId} 是您要嵌入的孪生的 ID。此处不支持 RealityPlan。

所需作用域

Section titled “所需作用域”

这两个操作都要求同一个访问令牌上具备两个作用域：

作用域原因
read:twin读取会话所针对的孪生
embed:twin为其签发嵌入会话

仅持有其中一个作用域的令牌会收到 403 Forbidden 以及 Insufficient OAuth scopes。请在开始之前就把两个作用域都添加到您的 OAuth 应用中；参见 Client Credentials 流程指南。

嵌入会话还使用一份独立且更严格的速率限制额度，与 API 的其余部分不同，因此请按每次查看会话创建一个会话，而不是按每次页面渲染创建。

create-session 响应

Section titled “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"
}
字段含义SDK 配置
iframeUrl嵌入查看器的基础 URL。使用前请将其补全——参见构建 iframe URL。iframeUrl，在您追加嵌入路由之后
token已签名的会话 JWT。SDK 需要它；嵌入的孪生用它进行身份验证。platformJWT
refreshToken与本次会话配对的 Base64 密钥。请将它保留在您的后端。—
expiresAt应当在此之前续订会话的 ISO 8601 时间点——它比 token 自身不再被接受的时刻早几分钟。—
apiUrl嵌入的孪生与之通信的区域 RealityTwin 后端（…/reality-twin）。它不是您在上面调用的 {api_url}——会话端点并不位于其上。backendUrl

refresh-session 返回相同的结构，但不含 iframeUrl 和 apiUrl。这两个值您只需获取一次：iframeUrl 在同一环境中是恒定的，而 apiUrl 在您所在组织的区域内是恒定的。

构建 iframe URL

Section titled “构建 iframe URL”

iframeUrl 是一个基础 URL，而不是一个已完成的 src。在同一环境中，它对每个孪生都是同一个常量——在生产环境中为 https://embed.prevu3d.com/reality-twin。请向它追加嵌入路由：

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

孪生 ID 不需要放进 URL——会话令牌已经标识了该孪生，查看器会从中读取它。

请用恰好一个斜杠连接两者：iframeUrl 结尾没有斜杠，因此 `${iframeUrl}/embed` 是正确的。

将补全后的 URL 交给 SDK：

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

令牌绝不出现在 URL 中

Section titled “令牌绝不出现在 URL 中”

会话 JWT 通过 SDK 的 INIT_CONFIG postMessage 握手，以 platformJWT 配置值的形式传送到 iframe。请不要把它作为查询参数追加到 iframe URL 上——嵌入的孪生并不会读取它，而且把一个有效凭据放进 URL 会让它暴露在浏览器历史记录、referrer 头和服务器日志中。

出于同样的原因，嵌入页面预期在 SDK 的 iframe 内运行。把补全后的 URL 单独粘贴到浏览器标签页中并不会加载孪生，因为那里没有任何东西会把令牌和后端 URL 交给它。

保持会话有效

Section titled “保持会话有效”

会话是短期有效的。请在 expiresAt 之前，从您的后端使用存储的 refreshToken 调用 refresh-session，持久化新的 refreshToken，并通过 twin.updateAccessToken(newAccessToken) 将新的 token 交给正在运行的 SDK——无需重新创建 iframe。完整模式请参阅快速入门的步骤 4。

后续步骤

Section titled “后续步骤”