이해하기

API 요청 헤더

• AR Live 은 Api 요청시 반드시 어플리케이션 토큰값을 헤더에 넣어주어야합니다.

• 해당 토큰은 맥스버스 콘솔사이트에서 어플리케이션 ID 와 어플리케이션 Key 로 요청하여 제공 받은 토큰값입니다.

• 용어의 혼동을 예방하기 위해 어플리케이션 ID 를 통해 발급받은 토큰을 어플리케이션 토큰 그 외의 AR Live 서버로부터 미팅에 접속하기 위해 발급받은 토큰을 AR Live 토큰 이라고 하도록 하겠습니다.

 "Authorization" : "Bearer ${Application_Token}"

User ID 관리

AR Live 서비스는 별도로 유저의 id 에 대한 체계를 관리하지 않습니다. 이로서 서비스 구축 서버 혹은 관리자가 유저 id 를 직접 관리를 할 수 있도록 구현 자유도를 높였습니다. 따라서 서비스를 이용하는 서비스 자체의 user 에 대한 id 값을 attendees , create_by , requester 와 같은 필드에 넣어주기만 하면됩니다.

방 생성

방을 생성시 편의를 위해 콘솔에서 기본 방 설정을 할 수 있습니다. 아래 설정을 하시면 방을 생성될 시 자동으로 아래 옵션을 통해서 만들어집니다.

기본설정시 해당 옵션들을 기준으로 방이 생성됩니다.

필요에 따라, 방을 생성하여 즉시 입장이 용이하도록 is_token_recieve를 true로 생성 요청하면 방에 접근 가능한 토큰(AR Live 토큰) 을 응답바디로 반환 받을 수 있습니다. 캘린더 형식으로 방을 예약, 관리가 가능하도록 예약시간(시작시간, 종료시간)을 설정 할 수 있습니다. 공개방인 경우, 참석자 등록 없이 모두가 방에 접속할 수 있습니다. 미팅에 참여할 수 있는 시간을 관리할 수 있도록 is_joinable 필드를 제공하여, true 인 경우에만 참가자들이 방에 참여할 수 있도록 합니다. 호스트권한이 있는 참석자에게는 참석자 강제 블락(강퇴), 방송 강제 종료 등의 특수기능을 제공합니다.

생성시 필요한 필수값은 REQUIRED 로 description에 표기하였습니다.

방 생성 요청 파라미터

parameter	type	description
name	string	해당하는 Room의 이름을 보여줍니다 REQUIRED
created_by	string	Room 생성에 대한 요청자의 id 를 의미합니다 REQUIRED
is_public	boolean	Room의 공개여부를 나타냅니다. default 값은 true입니다.
max_attendee_count	number	Room 에 참여할 수 있는 최대 유저수입니다. default 값은 16 입니다.
reserved_start_time	Date	Room의 예약 시작 시간 입니다. default 값은 현재시간 입니다
reserved_end_time	Date	Room의 예약 종료 시간 입니다. default 값은 현재시간 + 1h 입니다
description	string	Room에 대한 설명을 의미합니다.
attendees	string[]	참가자의 profile_id 목록을 담아서 요청하면 참가예약 상태로 등록이 됩니다.
is_token_receive	boolean	true 로 설정하면, 방 생성 요청 응답에 방 접속 Token을 받을 수 있습니다. REQUIRED
host_selection_type	ENUM(CREATOR, FIRST_ENTER_USER)	방의 호스트 선정 방식입니다. REQUIRED
is_elect_host	boolean	호스트가 미팅중 방을 나갔을 때, 호스트를 자동부여 할지 설정합니다. REQUIRED
is_joinable	boolean	true 가 되면 방에 입장 가능한 상태가 됩니다. 필요에 따라 참가자들의 입장을 막은 후, 특정 이벤트에 입장을 허용하는데 사용될 수 있습니다. REQUIRED

• API를 요청하여 만들어진 방은 개발자 콘솔의 방목록 페이지에서 확인이 가능합니다.

• <주의!> 콘솔의 AR Live 섹션에서 방생성 설정 옵션을 설정했으면 host_selection_type , is_elect_host , is_joinable 의 값은 콘솔에 설정된 값으로 적용됩니다.

방 정보 수정

방에 대한 정보를 수정하고 싶은 경우가 있습니다. 이를 위해서 방을 수정할 수 있는 api 를 제공하여 수정할 수 있도록 제공해줍니다. 하지만 특정시점 및 특정정보를 변경할 시 정보에 혼란을 줄 수 있는 상황이 발생될 수 있습니다. 이로인해서 AR Live 서비스는 특정 Room의 Status ( 아래 Room Status 참조) 에 따라, 제한된 정보만 바꿀 수 있도록 규칙을 정했습니다. Room Status 는 방 상세 정보 요청의 응답에서 확인할 수 있습니다.

• 수정 가능 프로퍼티

  • name
  • max_attendee_count
  • is_public
  • reserved_start_time
  • reserved_end_time
  • description
  • is_joinable
  • max_attendee_count

• 수정 불가능 프로퍼티

  • host_election_type
  • is_elect_host

• 방 정보 수정 규칙

  • 방 생성자, 호스트만이 방 정보 수정이 가능합니다.
  • reserved_start_time 은 reserved_end_time 이후의 시간으로 요청할 수 없습니다.
  • reserved_start_time 과 reserved_end_time 은 현재시간을 기준으로 이후 시간에 대해서만 수정이 가능합니다.
  • 방의 상태가 예약상태(room_status가 RESERVED) 인 경우, 위 프로퍼티들에 대한 수정이 가능합니다.
  • 방의 상태가 미팅중이거나 휴지상태(room_status가 MEETING or IDLE) 인 경우
    • reserved_start_time, reserved_end_time, is_joinable 에 대한 변경은 불가합니다.
    • max_attendee_count 에 대한 값을 변경하는 경우 현재 참여중인 유저의 수보다 커야합니다.
  • 방의 상태가 종료상태(room_status 가 ENDED) 인 경우 방 수정은 불가능합니다.

방 접속 토큰 발급

Room에 접속하기 위해서는 AR Live 토큰 을 AR Live 서비스로 부터 발급받아야합니다. 참석자는 똑같이 AR Live 토큰 을 발급받아 들어가야하며 이 과정속에서 Room에 입장할 수 있는 타당한 유저인지를 방접속 규칙(policy)에 의해 판별하게 됩니다.

• 방 접속 규칙
  • is_joinable이 false 인 방은 호스트를 제외하고 접속할 수 없습니다. false 인 경우 방정보 수정을 통해서 다른사람들이 접속하도록 수정이 가능합니다.
  • 방 참석자는 해당 방에서 추방당한 이력이 없어야 합니다. 추방당한 참가자는 is_blocked 가 true 입니다.
  • 방 참석자는 비공개방 (is_public가 false) 인 경우 방의 예약자 리스트에 있어야합니다.
  • 예약자는 is_reserved 가 true 이거나 is_invited 가 true 상태를 가집니다
  • 방 참석자가 예약자 리스트에 없는경우 참여자 추가, 초대 API 요청을 통해서 등록된 경우 방에 접속할 수 있습니다.
  • 방의 상태가 종료상태(room_status가 ENDED)( 아래 Room Status 참조)인 경우에는 접속 할 수 없습니다.

방 접속 및 Host 권한

개요에서 설명드렸다시피 , 생성된 방에 한하여 유저들 및 방의 부가 기능을 핸들링할 수 있는 권한을 host 에게 위임합니다. 호스트는 방생성자 혹은 방에 첫번째로 참여한 유저에게 부여할 수 있습니다. 호스트는 방 생성시 host_selection_type에 CREATOR, FIRST_ENTER_USER 타입 선택을 하여 선정됩니다. host 는 유저에 대한 행동을 제한할 수도 , 혹은 종료로 방의 lifecycle 을 마칠 수 있는 권한을 가질 수 있습니다. host 가 행할 수 있는 행동들 및 규칙은 아래와 같습니다.
host_selection_type 가 FIRST_ENTER_USER 인 경우에는, 방의 room_status가 RESERVED 상태에서는 호스트가 정해지지 않은 상태이므로, 방을 만든 사람(created_by)가 호스트 권한을 가집니다

1. 유저의 행동제한 및 상태변경

   action	description
   참석자 강퇴	지정한 참석자들을 강퇴합니다.
   참석자 강퇴 해제 (참석자 블록 해제)	강퇴당해 접속 할 수 없는 유저의 재접속 권한을 다시 부여합니다
   참석자 초대	특정 참석자들을 초대할 수 있습니다.( 일반 유저도 유저를 초대할 수 있습니다.)
   발표자 등록	특정 유저를 발표자로 화면을 공유할 수 있도록 지정할 수 있습니다.
   호스트 권한 위임	호스트가 특정 지정한 호스트가 이닌 유저에 한하여 호스트의 권한을 위임할 수 있습니다.

   • 규칙(policy)

     • host 는 다른 host 를 위임할 수 있습니다.
     • 초대자는 reserved 되지 않더라도 방에 접속할 수 있는 권한을 가집니다.
     • 추방당한 참석자는 다시 방의 접속할 수 없습니다. (토큰발급이 불가능합니다.)

2. 방 종료

   action	description
   방 종료	현재 있는 방을 종료합니다.

3. 부가기능 (WIP)

   action	description
   방 녹화	현재 있는 방의 영상 원하는 녹화 layer에 맞게 녹화합니다

   • 규칙(policy)

     • 현재 방이 녹화중이면, 녹화를 다시 요청할 수 없습니다.
     • 녹화중 방의 끝나는경우 녹화는 자동종료됩니다.

방의 행위는 host 중심으로 이루어집니다.

방 종료와 휴지 상태

방에 유저가 아무도 없다면 방 종료라고 생각할 수 있습니다. 다만 AR Live는 방 종료와 사람이 아무도 없는것은 다른 state 로 인지합니다. 종료가 된 방은 다시 사용할 수가 없기 때문에, 재입장이 불가합니다. 휴지상태의 방은 다시 사용할 수 있고, 재입장이 가능합니다. 이를 구분하기 위해 방 종료에 대한 개념은 host 가 방종료 api 를 호출한 것을 기점으로 구분이 됩니다. 방의 유저만 0 이고 방종료 api 를 호출하지 않은경우는 종료된 상태가 아닌 휴지상태(IDLE) 입니다. 그에 따른 규칙은 아래 표를 참조하시면 됩니다.

state	rule
방 종료(ENDED)	host 가 방종료 api 를 호출했을 경우 해당 state 가 되며, 재입장 불가합니다.
휴지(IDLE)	방의 유저가 0명인 경우로 AccessToken 재발급으로 재입장이 가능합니다.

방 삭제

방삭제는 예약한 방에 대해서 삭제 할 수 있는 기능을 가지고 있습니다. 이에 대한 규칙은 다음과 같습니다.

• 방 삭제 규칙

  • host 만 방을 삭제 할 수 있는 권한을 가지고 있습니다.
  • MEETING 중인 방에서는 방을 삭제 할 수 없습니다. MEETING 상태인 방을 삭제하기 위해서는 방 종료 Api 를 호출한 후, 방 상테가 ENDED 상태로 전환된 후에 삭제를 할 수 있습니다.
  • ENDED 상태인 방은 ENDED 가 된 시점으로부터 7일이 지나면 자동으로 삭제됩니다 (WIP)

방 상태 (Room Status)

방(Room) 은 생성 시점서부터 종료시점 까지 state 를 가지게 됩니다. state 는 아래와 같습니다

state	description
RESERVED	처음 방을 생성하고 유저의 입장이 한번도 없는경우의 status 입니다.
MEETING	현재 방에 유저가 한명이라도 있는경우의 status 입니다.
IDLE	MEETING 상태에서 방에 유저가 한명도 없게 된경우 의 status 입니다.
ENDED	host 가 방의 종료 api 를 호출한 경우의 status 입니다.

즉 room 의 status 각각의 경우에서 다른 statue 로 trigger 될 수 있습니다.

[ROOM STATUS]

Room 시퀀스과정

is_token_receive가 true 인 경우와 false 인 경우에 대해서 접속하는 시점이 다르므로 나누어서 보도록하겠습니다. is_token_receive가 false 인 경우에는 일반적인 접속 과정과 똑같이 방 생성 후 토큰을 요청하는 방식으로 들어갑니다. 하지만 is_token_receive가 true 인 경우에는 생성자가 곧바로 방에 들어 갈 수 있도록 AR Live 토큰 을 같이 주도록 합니다. 아래 플로우를 보시면 위에서 설명드렸었던 요청이 어떠한 식으로 흘러가는지 확인해보실 수 있습니다. 방이 생성되고, 참여자가 방에 접속할 수 있는 AR Live 토큰을 발급 받은 후, 해당 으로 AR Live 서비스에 웹소켓 접속을 하면 비로소 참여자가 1명이 되고 방 상태는 MEETING 으로 전환됩니다.

is_token_receive 가 false

is_token_receive 가 true