[XRCLOUD팁] 외부 웹페이지에 동적 데이터를 전달할 수 있는 인라인뷰 컴포넌트의 개발 및 활용 방법
본 문서는 XRCLOUD의 가이드 문서 중 일부 입니다.
1. 문서의 목적 및 개요
- 웹기반의 메타버스 XRCLOUD는 다양한 외부 웹서비스나 페이지와 연결될 수 있는 기능을 제공합니다. Spoke웹 메탑버스 에디터에서 제공하는 컴포넌트는 link컴포넌트와 Image컴포넌트가 있으며, Image컴포넌트는 이미지를 버튼 처럼 사용할 수 있어 Image컴포넌트를 사용합니다.
- 하지만 Room은 Spoke로 만들어진 Scene(공간 프로젝트)을 인스턴스화한 공간으로 Image외 link컴포넌트에 들어간 link를 동적으로 변경하거나 혹은 해당 외부 웹사이트에 데이터를 전달할 수 없습니다.
- 이에 BELIVVR의 XRCLOUD에서는 InlineView컴포넌트를 만들어 Room에 접속할때 데이터를 전달하고 해당 데이터는 Room에 연결된 웹페이지에 전달 될 수 있도록 만들었습니다. 이를 통해 XRCLOUD를 이용한 개발자는 Room에 연결된 웹페이지에 데이터를 전달하여 유저별로 다른 목적 페이지로 라우팅 시키거나 혹은 유저별 맞춤 정보를 제공할 수 있습니다.
2. 인라인 뷰의 데이터 전달 및 사용 방법
1) 사전 준비
- Scene에 인라인뷰 컴포넌트를 배치합니다.
- 인라인뷰 컴포넌트는 거의 Image컴포넌트의 기능을 다 가지고 있으며, 차이점은 목적 페이지에 대한 타겟 프레임을 허브내에 별도로 만든 iframe으로 할 수 있도록 기능을 제공하며 두가지 iframe과 두가지 라우팅 유형이 제공됩니다.
- Main : 3D공간이 표기되는 영역입니다.
- Side View : PC에서 채팅과 접속자가 표기되는 영역으로 주로 모바일 형태의 콘텐츠에 적합합니다.
- Self Window : 전체 페이지를 라우팅합니다.
- New Window : 새탭을 띄워 해당 페이지를 라우팅합니다.
2) 호출
- 호출시에는 Room의 URL을 받아오는 getRoom API를 이용합니다.
- https://api.xrcloud.app/api/rooms/{roomId}
- 넘겨줄 데이터는 쿼리파라미터 형식으로 linkPayload에 실어 보냅니다.
- https://api.xrcloud.app/api/rooms/{roomId}?linkPayload={Data}
- 리턴한 URL중 private URL을 이용합니다. 해당 URL은 시간이 지나면 만료되는 linkPayload의 유출을 막기 위함입니다.
{
"id": "f24ee5ba-8f1f-4f7a-86ed-738f95ea1f8b",
"name": "example room name",
"size": 10,
"tags": [],
"sceneId": "c322b49b-6e12-47d9-b293-b5ab3727459c",
"createdAt": "2023-07-12T09:27:41.600Z",
"updatedAt": "2023-07-12T09:27:41.600Z",
"returnUrl": "https://www.google.com/",
"roomUrl": {
"public": {
"host": "https://room.xrcloud.app:4000/7UizZDL/example-room-name?public=35e75895-9db7-4eee-bae3-87e20ee156dc",
"guest": "https://room.xrcloud.app:4000/7UizZDL/example-room-name?public=a0166051-1eee-44bb-922a-c988d517a0e1"
},
"private": {
"host": "https://room.xrcloud.app:4000/7UizZDL/example-room-name?private=fdc306b9-5129-4d83-86d5-52836afeee7e",
"guest": "https://room.xrcloud.app:4000/7UizZDL/example-room-name?private=72dde871-33d7-4aa3-a8a9-73b8b5f0458d"
}
},
"thumbnailUrl": "https://api.xrcloud.app/files/852a6f47-3978-4201-a637-9699d7845266.jpg"
}3) 유저의 사용
- 앞서 받아온 private URL로 접속한 이용자는 inlineView을 클릭하면 해당 inlineView 사전에 설정된 목적URL로 이동하며 linkePayload에 전달되었던 데이터를 hubsParam이라는 이름의 쿼리파라미터를 추가하여 전달합니다.
- InlineViewName으로는 유저가 클릭한 인라인뷰의 이름이 넘어와서 이 데이터를 확인하여 어떤 컴포넌트를 클릭하여 유저가 해당 페이지에 접근했는지를 알려줍니다.
3. 활용 방법
1) 사용자별 맞춤 정보 제공
- LinkPayload에 사용자 식별 정보를 실어 전달하여 사용자의 정보를 보여줄 수 있는 기능을 제공할 수 있습니다.
2) 사용자별 라우팅 페이지 제공 및 자동 라우팅
- 사용자별로 공간의 이동이 가능한 선택을 제공할 수 있습니다.
- 이때 형식은 인라인뷰는 Self Window를 이용합니다.
- XRCLOUD Room의 링크를 통해 이동시에는 페이드아웃이 일어나는 트랜짓효과의 자연스러운 이동이 가능하지만 인라인뷰를 이용한 이동은 아직 지원하고 있지않아서 페이지 전체가 리다이렉션되는 불편함이 있습니다.
- 선택이 아니라 개발자(플랫폼)가 즉시 라우팅 시킬 수도 있습니다.
3) CP(콘텐츠프로바이더)에게 공통 데이터 전달
- 공간을 편집하고 제공하는 CP(콘텐츠 프로바이더)에게 플랫폼의 공통 파라미터를 공지하여 각 콘텐츠간에 필요한 공통 데이터를 전달할 수 있습니다.
- 예를 들어 저희가 개발중인 플랫폼에서는 외부 콘텐츠에서 플랫폼의 아바타와 표시이름을 받아 플랫폼의 사용자 일관성을 유지하고 싶어합니다.
- 따라서 저희는 linkpayload에 아바타와 이름을 전달하는 것을 플랫폼의 공통규약으로 만들어서 배포했습니다.
- Create Scene
- 서비스 어드민에서는 XRCLOUD의 Scene Create API를 통해 CP별로 공간을 제작하고 있습니다.
- 1–1. 공간 제작시 Spoke에디터에서 자유롭게 인라인뷰를 사용하여 각 CP들은 여러 외부 콘텐츠를 Room과 연결할 수 있습니다. 그 중에는 Unity Webgl콘텐츠도 있습니다.
- 1–2~4. 서비스 플랫폼에서 Scene을 배포하면 자동으로 Create Room API를 통해 Room도 만들어서 1:1구조로 개발하였습니다.
2. GetRoom API
- 유저가 사용하는 서비스 페이지에서는 유저가 Room을 접근하기 위한 Private URL을 요청하는데 이 때 유저의 아바타정보와 이름정보를 Payload에 함께 실어 보냅니다.
3~4. Return Private room URL & Open Room url
- 플랫폼은 유저가 접근할 수 있는 Private URL을 받게 됩니다. 이 URL을 화면에 노출하면 사용자는 해당 URL(버튼)을 클릭하여 Room으로 접근합니다.
5. Open Page and Send payload
- 유저가 접속한 Room에서 inlineView컴포넌트를 클릭하면 해당 컴포넌트는 Scene을 생설할때 설정한 InlineView의 아웃링크 서비스 페이지에 Payload정보와 InlineView의 이름을 쿼리파라미터로 전달합니다.
- CP는 해당 파라미터를 파싱하여 아바타와 이름을 동일하게 처리합니다.
ex) 메타트랙의 CP에게 전달한 공지사항
- hubsParam에는 필요한 파라미터가 전달됩니다. 메타트랙에서는 | 를 구분자로 수업id, 사용자id(uuid), 사용자이름, 아바타URL, 메타트랙에서 로그인 처리를 할 수 있는 토큰을 붙여서 전달했습니다.
- inlineViewName은 Spoke에서 정의한 inlineView컴포넌트의 이름입니다.
- 파라미터는 반드시 수업의 입장하기를 통해 생성되는 임시(private) URL로 접근 하셔야만 전달됩니다. 만료되는 임시url이므로 정적url로 사용하시면 나중에 접근이 되지 않습니다. 참고로 어드민에는 수업정보, 아바타 정보등의 보낼 정보가 없고, 해당 url은 고정 public을 이용합니다.
