콘텐츠로 이동
Prevu3D

임베드 세션

임베드 세션은 RealityTwin이 페이지 안에서 렌더링될 수 있도록 해 주는 단기 권한입니다. 백엔드가 RealityConnect API를 통해 세션을 생성하고 브라우저에 안전한 값을 프런트엔드로 전달하면, 프런트엔드가 그 값을 SDK에 넘깁니다. 이 페이지는 그 두 엔드포인트와 이들이 반환하는 모든 필드, 그리고 직접 조립해야 하는 단 하나의 값인 iframe URL에 대한 참조입니다.

두 가지 세션 엔드포인트

섹션 제목: “두 가지 세션 엔드포인트”

두 작업 모두 트윈 컨텍스트에 있으며, 인터랙티브 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은 여기서 지원되지 않습니다.

필요한 스코프

섹션 제목: “필요한 스코프”

두 작업 모두 동일한 액세스 토큰에 두 가지 스코프가 필요합니다.

스코프용도
read:twin세션이 대상으로 하는 트윈 읽기
embed:twin해당 트윈에 대한 임베드 세션 발급

둘 중 하나만 가진 토큰은 Insufficient OAuth scopes와 함께 403 Forbidden을 받습니다. 시작하기 전에 OAuth 애플리케이션에 두 스코프를 모두 추가하세요. Client Credentials 플로우 가이드를 참조하세요.

또한 임베드 세션은 API의 나머지 부분과 달리 더 엄격한 전용 속도 제한 예산을 사용하므로, 페이지 렌더링마다가 아니라 열람 세션마다 하나의 세션을 생성하세요.

create-session 응답

섹션 제목: “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 만들기

섹션 제목: “iframe URL 만들기”

iframeUrl은 완성된 src가 아니라 베이스 URL입니다. 한 환경 안에서는 모든 트윈에 대해 동일한 상수이며, 프로덕션에서는 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에 담기지 않습니다

섹션 제목: “토큰은 URL에 담기지 않습니다”

세션 JWT는 SDK의 INIT_CONFIG postMessage 핸드셰이크를 통해 platformJWT 구성 값으로 iframe에 전달됩니다. 쿼리 매개변수로 iframe URL에 덧붙이지 마세요. 임베드된 트윈은 쿼리 매개변수를 읽지 않으며, 유효한 자격 증명을 URL에 담으면 브라우저 기록, referrer 헤더, 서버 로그에 노출됩니다.

같은 이유로 임베드 페이지는 SDK의 iframe 안에서 실행되도록 설계되어 있습니다. 완성된 URL을 브라우저 탭에 그대로 붙여 넣으면 토큰과 백엔드 URL을 전달할 주체가 없으므로 트윈이 로드되지 않습니다.

세션 유지

섹션 제목: “세션 유지”

세션은 수명이 짧습니다. expiresAt 이전에 저장해 둔 refreshToken으로 백엔드에서 refresh-session을 호출하고, 새로 받은 값을 저장한 다음, 새 token을 twin.updateAccessToken(newAccessToken)으로 실행 중인 SDK에 전달하세요 — iframe을 다시 만들 필요는 없습니다. 전체 패턴은 시작하기의 4단계를 참조하세요.

다음 단계

섹션 제목: “다음 단계”