XRCLOUD API (1.1)

해당 문서의 모든 API 호출은 ApiKey를 필요로 합니다.

• ApiKey는 XRCLOUD 페이지에 로그인 한 후 페이지 우상단의 My page에서 발급 받을 수 있습니다.

XRCLOUD는 Room과 Scene의 이벤트 발생 시 설정된 webhook URL로 로그를 전송합니다.

Room 관련 이벤트

• room-join: 사용자가 Room에 입장
• room-exit: 사용자가 Room에서 퇴장
• room-video-click-event: Room 내 비디오 클릭 이벤트

Scene 관련 이벤트

• scene-created: Scene 생성
• scene-updated: Scene 수정

Webhook 요청 정보

• Method: POST
• Headers:
  • Content-Type: application/json
  • X-Forwarded-For: 사용자 IP

요청 데이터 형식

{
  "code": "room-join",              // 이벤트 코드
  "resourceId": "uuid",            // Room/Scene의 ID
  "sessionId": "uuid",             // 세션 ID
  "reticulumId": "string",         // XRCLOUD(Hubs)의 사용자 ID
  "logTime": "2024-01-01T00:00:00Z", // 이벤트 발생 시간
  "action": "string",              // 이벤트 액션 정보 (예: "enter", "exit")
  "ip": "string",                  // 사용자 IP (X-Forwarded-For 헤더에서 추출)
  "userAgent": "string",           // 사용자 브라우저 정보
  "device": "string"               // 사용자 디바이스 정보 (pc/mobile/vr)
}```

**참고**: 
- webhook URL은 Project 생성 시 또는 Project 정보 수정 시 설정할 수 있습니다.
- 현재 ip와 userAgent 값은 제대로 전송되지 않을 수 있습니다.
- webhook 요청에 대한 응답이 300 이상의 상태 코드를 반환하면 오류로 처리됩니다.

XRCLOUD의 Project는 개발자의 프로젝트, 플랫폼, 또는 3rd-party 애플리케이션이 될 수 있습니다. 이는 Scene과 Room을 관리하는 단위로, 여러 Scene과 Room이 특정 Project에 속하게 됩니다.

• webhookUrl은 XRCLOUD 페이지에서 Project를 생성하거나 정보를 수정할 때 설정할 수 있습니다.

웹페이지 기반의 3D 가상공간을 제작하는 공간으로 Room을 생성할 때 필요한 공간입니다.

get-creation-url api를 호출하면 얻을 수 있는 필드 중 'sceneCreationUrl'에 접속하여 에디터(Spoke)에 접근한 후 우상단의 Publish Scene 버튼을 통해 Scene을 생성할 수 있습니다. 또, get-scene api를 호출하면 얻을 수 있는 필드 중 'sceneModificationUrl'에 접근하여 수정합니다.

• optId 값은 XRCLOUD에서 Scene의 생성 및 수정을 확인하기위한 callback value 입니다. 변형하여 사용하면 오류가 발생할 수 있습니다.

Room은 에디터(Spoke)를 통해 생성된 Scene으로 구성된 공간입니다.

각 Room에는 정보 요청 시마다 주소가 변하는 private room URL과 고정된 주소를 가진 public room URL이 있습니다. 이 URL들은 또한 방의 호스트에게 권한을 부여하는 host URL과 게스트 권한을 부여하는 guest URL로 구분됩니다.

'returnUrl'은 방을 떠날 때 돌아갈 웹 주소를 의미하며, XRCloud의 Rooms 탭에서 설정할 수 있습니다.