시작하기

이 가이드는 RealityTwin을 임베드하는 데 필요한 두 가지 통합을 안내합니다. 즉, (백엔드에서) RealityConnect API에 대해 임베드 세션을 생성하는 것과 (프런트엔드에서) 그 세션을 SDK에 전달하는 것입니다. SDK 자체에 특화된 모든 내용(설치 세부 정보, 초기화, 전체 명령 및 observable 표면, 오류 코드, 실행 가능한 플레이그라운드)은 신뢰할 수 있는 출처인 @prevu3d/realityconnect-embed 패키지의 README에 있습니다.

사전 요구 사항

시작하기 전에 다음을 준비하세요.

조직의 보안 설정에서 RealityConnect Embed가 활성화된 Enterprise 요금제.
Client Credentials 플로우를 사용하는 RealityConnect API OAuth 애플리케이션. 아직 설정하지 않았다면 먼저 Client Credentials 플로우 가이드를 따르세요.
임베드하려는 트윈의 ID.
SDK를 설치할 계정에 대한 비공개 prevu3d/realityconnect-embed GitHub 리포지토리의 읽기 접근 권한. 접근 권한은 요청에 따라 고객별로 수동으로 부여됩니다. 접근이 필요한 GitHub 사용자 이름을 **고객 성공 관리자(CSM)**에게 전달하면 Prevu3D가 이들을 리포지토리에 추가합니다. GitHub Packages의 패키지 가시성은 리포지토리 가시성을 따르므로 read:packages PAT만으로는 충분하지 않으며 리포지토리 접근 권한도 필요합니다.

전체 연동 방식

대략적으로 임베드 세션은 다음과 같이 흐릅니다.

백엔드가 RealityConnect API에 인증하고 특정 트윈에 대해 create-session을 호출합니다. API는 토큰과 URL을 반환합니다.
백엔드는 브라우저에 안전한 값(세션 토큰, iframe 베이스 URL, 리전 API URL)을 프런트엔드로 전달합니다.
프런트엔드는 이 값들을 SDK에 전달하고, SDK는 iframe을 삽입하여 트윈과 양방향 채널을 엽니다.
현재 토큰이 만료되기 전에 백엔드가 refresh-session을 호출하고 새 값을 프런트엔드로 다시 전달합니다.

OAuth 클라이언트 시크릿은 절대 브라우저에 도달해서는 안 되며, 백엔드만 사용합니다.

1단계: 임베드 세션 생성(백엔드)

임베드 세션 관리는 RealityConnect API를 재사용합니다. Client Credentials 플로우 가이드에 설명된 대로 정확히 Client Credentials 플로우로 인증한 다음, 트윈에 대해 두 가지 임베드 세션 작업을 호출합니다.

작업	목적
`GET {api_url}/v1/twin/{contextId}/embed/create-session`	세션을 시작합니다. `iframeUrl`, `token`, `refreshToken`, `expiresAt`, `apiUrl`을 반환합니다. 본문은 없습니다.
`POST {api_url}/v1/twin/{contextId}/embed/refresh-session`	(본문에 담아 보낸) `refreshToken`을 새 `token` 및 `refreshToken`과 교환합니다.

두 호출 모두 Client Credentials 플로우에서 얻은 bearer 액세스 토큰을 Authorization 헤더에 사용하며, 두 호출 모두 해당 토큰에 read:twin 및 embed:twin 스코프가 필요합니다. 임베드 세션이 이 두 작업에 대한 전체 참조이며, 인터랙티브 API 참조는 이들의 스키마를 게시합니다.

2단계: SDK 설치(프런트엔드)

GitHub 계정에 접근 권한이 부여되면(사전 요구 사항 참조), 비공개 GitHub Packages npm 레지스트리에서 SDK를 @prevu3d/realityconnect-embed로 설치합니다. SDK README에는 일회성 .npmrc 및 Personal Access Token 설정이 처음부터 끝까지 문서화되어 있습니다.

3단계: 세션을 SDK에 전달

create-session 응답 필드를 백엔드에서 프런트엔드로 전달하고 SDK 구성에 매핑합니다.

`create-session` 필드	SDK 구성	비고
`iframeUrl`	`iframeUrl`	베이스 URL입니다. 임베드 경로를 직접 덧붙이세요: `${iframeUrl}/embed`. 트윈 ID는 URL에 들어가지 않으며, 세션 토큰이 트윈을 식별합니다. iframe URL 만들기를 참조하세요.
`apiUrl`	`backendUrl`	임베드가 통신하는 리전 RealityTwin 백엔드. 1단계에서 호출한 `{api_url}`이 아닙니다.
`token`	`platformJWT`	임베드가 인증에 사용하는 서명된 세션 토큰. URL 매개변수가 아니라 SDK를 통해 iframe에 전달됩니다.

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

그 이후에는 SDK README를 따라 패키지를 설치하고, 뷰어를 초기화하고, 트윈을 제어하세요.

4단계: 세션 유지

임베드 세션은 수명이 짧습니다. create-session이 반환하는 token은 대략 응답에 표시된 expiresAt 시점에 만료됩니다. 그 기간을 넘어 트윈을 계속 실행하려면 백엔드에서 세션을 갱신하고 새 액세스 토큰을 실행 중인 SDK에 전달하세요 — iframe을 다시 만들 필요가 없습니다.

일반적인 패턴:

백엔드에서, 현재 사용자의 트윈에 대해 저장된 refreshToken을 읽고, refresh-session을 호출하고, 새 refreshToken을 저장하고, 새 token(및 기타 세션 필드)을 브라우저에 반환하는 엔드포인트를 제공합니다.
프런트엔드에서, 현재 토큰이 만료되기 직전에 갱신을 예약합니다.
새 세션이 도착하면 twin.updateAccessToken(newAccessToken)을 호출하여 새 액세스 토큰을 실행 중인 SDK에 전달합니다:
```
await twin.updateAccessToken(newAccessToken);
```
트윈은 다음 백엔드 요청에서 새 JWT를 이어서 사용합니다 — 열린 구독, 카메라 상태, 로드된 워크플로는 모두 유지됩니다. 이 호출은 수락 시 true, 거부 시 false로 resolve됩니다(onError를 통해서도 알림). onReady가 발생하기 전에 호출하면 RealityConnectEmbedError('TWIN_NOT_READY')가 throw됩니다.

정확한 예약 전략(만료 전 고정 타이머, 사용자 활동 시, 탭 가시성 변경 시 등)은 애플리케이션에 달려 있습니다.

유의할 사항

페이지가 인터페이스를 소유합니다. 임베드는 순수 뷰어입니다. 자체 컨트롤을 구축하고 SDK 명령에 연결하세요. 임베드가 포함하는 것과 포함하지 않는 것은 소개를 참조하세요.
자격 증명은 서버 측에 보관하세요. 세션의 요청과 갱신은 백엔드에서만 수행하세요.
세션은 만료됩니다. 통합의 일부로 토큰 갱신을 계획하세요.
Enterprise 및 보안 설정. 임베드는 조직에 대해 활성화된 경우에만 로드됩니다.

SDK 참조

@prevu3d/realityconnect-embed 패키지는 SDK 작업을 위한 완전한 참조입니다. 다음 내용은 해당 README를 읽어 보세요.

비공개 GitHub Packages 레지스트리를 위한 .npmrc 및 Personal Access Token 전체 설정
RealityConnectEmbed.init(config) 구성 참조
각 네임스페이스의 액션 및 상태 observable(내비게이션, 객체, POI, POV, 유틸리티)
공유 가능한 링크를 위한 카메라 뷰 인코딩 플로우
문서화된 모든 오류 코드와 발생 조건
명령 표면을 탐색하기 위해 라이브 트윈을 가리킬 수 있는 실행 가능한 플레이그라운드

다음 단계

임베드 세션: 세션 엔드포인트, 모든 응답 필드, iframe URL을 만드는 방법.
소개: 기능 개요.
Client Credentials 플로우: 이 가이드가 기반으로 하는 인증.
인터랙티브 API 참조: RealityConnect API 전체 카탈로그.
GitHub의 라이브 예제: 복사해서 사용할 수 있는 동작하는 Vue.js 통합.
@prevu3d/realityconnect-embed: 소스 리포지토리