이해하기
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
orIDLE
) 인 경우- 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)가 호스트 권한을 가집니다
유저의 행동제한 및 상태변경
action description 참석자 강퇴 지정한 참석자들을 강퇴합니다. 참석자 강퇴 해제 (참석자 블록 해제) 강퇴당해 접속 할 수 없는 유저의 재접속 권한을 다시 부여합니다 참석자 초대 특정 참석자들을 초대할 수 있습니다.( 일반 유저도 유저를 초대할 수 있습니다.) 발표자 등록 특정 유저를 발표자로 화면을 공유할 수 있도록 지정할 수 있습니다. 호스트 권한 위임 호스트가 특정 지정한 호스트가 이닌 유저에 한하여 호스트의 권한을 위임할 수 있습니다. 규칙(policy)
- host 는 다른 host 를 위임할 수 있습니다.
- 초대자는 reserved 되지 않더라도 방에 접속할 수 있는 권한을 가집니다.
- 추방당한 참석자는 다시 방의 접속할 수 없습니다. (토큰발급이 불가능합니다.)
방 종료
action description 방 종료 현재 있는 방을 종료합니다. 부가기능 (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
