Quick Guide에서는 Web 버전의 카카오 i 커넥트 라이브 SDK 2.0을 이용하여 Web 환경에서 음성 채팅 서비스를 직접 구현하면서 SDK 기본 요소와 개념을 살펴보도록 하겠습니다.
음성 채팅 서비스는 다수의 참여자들이 한 방(Room)에 모여 이야기를 나누는 서비스입니다. 음성 채팅 서비스를 처음부터 개발하는 것은 어려운 과정일 수 있지만, 카카오 i 커넥트 라이브 SDK를 사용하면, 채팅방을 생성하고, 음성을 송출하고, 채팅방에서 발생하는 일련의 이벤트를 처리하는 것 만으로 음성 채팅 서비스를 쉽게 개발할 수 있습니다.
Quick Guide에서 SDK 기본 개념과 대략적인 개발 순서를 이해한다면, 다양한 라이브 스트리밍 서비스를 어렵지 않게 구현할 수 있을 것입니다. 기본적인 음성 채팅 서비스를 구현하는 것 외에, 발화자 확인 또는 화면 공유 기능 등 SDK가 제공하는 확장 기능을 구현하고 방법은 기능 확장하기를 참고하시기 바랍니다.
안내
현재 Quick Guide는 Web 버전을 기준으로 합니다. iOS 및 Android 용 Quick Guide는 업데이트 예정입니다. Web 버전의 상세 개발 과정은 [카카오 i 기술문서] 개발자 가이드 > Web 문서를 참고하시기 바랍니다.
SDK 기본 개념
카카오 i 커넥트 라이브 SDK 2.0을 사용하여 라이브 스트리밍 서비스 개발 시, SDK의 기본 개념을 이해하는 것이 중요합니다.
카카오 i 커넥트 라이브 SDK 2.0에서는 Participant(참여자), Room(채팅방), Media(미디어)의 기본 클래스가 존재하며, 이 클래스는 SDK 개발 전반에 사용됩니다. 즉, SDK를 사용한 서비스 개발 과정은 이 3개의 기본 클래스를 조작하는 과정이라고 할 수 있습니다. 이 3개의 기본 클래스가 SDK에서 동작하는 흐름을 살펴보면, 먼저 참여자(Participant)는 createRoom() 메서드를 통해 특정 채팅방(Room)을 생성하여 입장합니다. 참여자(Participant)가 채팅방에 입장한 후에는 자신이 만든 로컬 미디어(LocalMedia)를 publish() 메서드를 통해 채팅방(Room)에 전송하거나, 또는 subscribe() 메서드를 통해 채팅방(Room)에서 리모트 참여자(Remote Participant)가 만든 리모트 미디어(ReomoteMedia)를 전송받습니다.
그림SDK 기본 클래스
표SDK 기본 클래스
클래스
설명
participant
라이브 스트리밍 서비스의 채팅방에 참여한 참여자
Room
참여자들이 입장하는 채팅방
Media
미디어 생성 주체에 따라 다음으로 구분 됨 - LocalMedia(로컬 미디어): 자신의 미디어 - RemoteMedia(리모트 미디어): 상대방의 미디어
카카오 i 커넥트 라이브 SDK를 사용하여 음성 채팅을 포함한 라이브 스트리밍 서비스를 개발하는 대략적인 흐름은 다음과 같습니다. 상세한 개발 가이드는 [카카오 i 기술문서] 개발자 가이드 > Web 문서를 참고하시기 바랍니다.
그림Web SDK 개발 흐름
signIn() 메서드를 사용하여 카카오 i 커넥트 라이브에 로그인 및 인증을 수행합니다. 인증 시 카카오 i 커넥트 라이브 콘솔에서 서비스 인증 정보를 발급받아 인자로 전달해야 합니다. 인증 및 키(Key) 처리에 대한 자세한 설명은 [카카오 i 기술문서] 인증 및 키 처리 문서를 참고하시기 바랍니다.
안내
무료 사용자도 콘솔에 회원가입을 할 경우, 개발과 테스트를 수행할 수 있습니다. 단, 무료 계정의 경우 다음의 제약 사항이 적용됩니다. - 채팅방(Room)마다 최대 3분까지 테스트 가능(동일 방에서 여러 번 테스트는 가능 - 하나의 채팅방(Room)만 개설 가능
createRoom() 메서드를 사용하여 참여자들이 입장하는 채팅방(Room)을 생성합니다. Room을 생성하는 즉시 Room과 관련된 다양한 이벤트(입장/퇴장 목록, 현재 발화자 정보, 카메라 사용 여부, 영상 송출 정보 등)를 수신할 수 있습니다. 이벤트와 관련한 자세한 설명은 Event를 확인하시기 바랍니다.
자신의 미디어인 LocalMedia(로컬 미디어)를 생성합니다.
publish() 메서드를 사용하여 LocalMedia를 Room에 송출합니다.
채팅방을 종료하고 로그아웃합니다.
음성 채팅 서비스 구현하기
음성 채팅 서비스는 영상 배치나 카메라 권한 허용 등의 복잡한 작업이 필요하지 않기 때문에 카카오 i 커넥트 라이브 SDK를 가장 쉬운 방식으로 사용해 볼 수 있는 예제라고 할 수 있습니다.
예제를 살펴보면서 SDK 기본 개념에서 설명한 Room(채팅방)과 LocalMedia(로컬 미디어), Participant(참여자) 클래스의 개념과 이들의 동작 관계를 살펴보도록 하겠습니다.
Step 1. 개발 환경 설정하기
Quick Guide에서는 온라인 IDE(Integrated Development Environment) 환경과 로컬 환경을 구분하여 개발 환경을 설명합니다. Stackblitz 또는 Codesandbox 등의 온라인 웹 개발 환경을 사용하는 경우 별도로 개발 환경을 설정하지 않아도 테스트가 가능합니다. 단, 로컬 방식을 사용하는 경우에는 Node.js가 실행될 수 있는 환경과 http-server 등의 정적(Static) 파일 웹서버 환경을 준비하시기 바랍니다.
자신의 PC 환경에서 웹 서버를 설치하여 테스트할 경우 HTTP 웹서버 환경이 필요하며, 본 문서에서는 http-server를 사용합니다.
코드예제상세 설정
Bash
//http-server를 개인 PC에 설치하고 html파일이 있는 특정 프로젝트 폴더에서 실행
> npm i -g http-server
> mkdir audiotest
> cd audiotest
> touch index.html
> echo "hello connectlive">>index.html
> http-server # browser로 http://localhost:8080
안내
본 문서의 모든 소스 코드는 Github Repository에서 다운로드할 수 있습니다. 이 경우, 별도의 과정 없이 바로 git clone 명령으로 소스를 다운로드 후 http-server를 실행하여 테스트 및 학습을 수행할 수 있습니다.
Step 2. SDK 설치 및 HTML 페이지 구성하기
SDK를 이용한 웹 기반 프로젝트를 테스트하기 위해서는 먼저 웹 프로젝트를 새롭게 작성하고, HTML 파일을 새로 작성해야 합니다.
음성 채팅을 위한 HTML 화면은 영상을 배치할 필요가 없으므로, 최대한 간단하게 [연결] 버튼과 [종료] 버튼으로 구성합니다.
[연결] 버튼을 클릭 시, 즉시 특정 음성 채팅방으로 연결되어 대화할 수 있습니다. 반대로 [종료] 버튼을 클릭하면 모든 대화가 종료되고 초기화됩니다. SDK 설치 및 HTML 화면 구성 코드는 다음과 같습니다.
그림SDK 설치 및 HTML 화면 구성
코드예제SDK 설치 및 HTML 화면 구성
HTML
<html>
<head>
<title>connectlive test page</title>
<meta charset="UTF-8" />
<script src="https://cdn.jsdelivr.net/npm/@connectlive/connectlive-web-sdk/dist/connectlive-web-sdk.min.js"></script>
</head>
<body style="background-color: #f7e600">
<div id="app"></div>
<h1>카카오 i 커넥트 라이브 음성채팅 샘플</h1>
<button id="connectButton">Connect</button>
<button id="disconnectButton">Disconnect</button>
<script></script>
</body>
</html>
Step 3. 카카오 i 커넥트 라이브에 로그인하기
HTML 화면을 구성 후, 카카오 i 커넥트 라이브에 로그인을 진행해야 합니다. 로그인은 무료 사용자라도 반드시 수행하는 절차로서, 처음 서비스에 진입 시 단 한 번만 수행하면 됩니다. 로그인 시 signIn() 메서드를 사용하며, 이는 promise 객체이므로 await 등을 사용하는 것이 좋습니다.
실제 서비스를 사용하기 전이라면, 미리 로그인을 하는 것을 권장합니다. 하지만 Quick Guide에서는 [연결] 버튼을 클릭할 때 로그인을 시도하도록 구현하겠습니다. 로그인 시, 카카오 i 커넥트 라이브 콘솔에서 서비스 인증 정보를 발급받아 인자로 전달해야 합니다.
OAuth 2.0 연동에서 토큰 관련 작업을 수행하기 위한 프로비저닝 서버의 엔드포인트 - https://icl2-provisioning-ap2.k9ertc.io/api/rpc로 고정
serviceId
String
필수
각 워크스페이스에 할당되어있는 공개 ID로, 서비스 구분에 활용되는 유일값 - 콘솔에서 발급
serviceSecret
String
선택
각 participant(참여자)에게 할당되는 임시 비밀키 - 콘솔에서 발급
token
String
선택
서비스에서 발급받은 토큰 - 서비스 자체 인증인 경우에만 필요
errorHandler
ErrorHandler
필수
에러 상황을 처리하기 위한 핸들러
안내
카카오 i 커넥트 라이브 SDK 2.0는 커넥트 라이브 내부 인증과 서비스 자체 인증 방식을 모두 지원합니다. 인증 과정 및 키(Key) 처리에 대한 자세한 설명은 [카카오 i 기술문서] 인증 및 키 처리 문서를 참고하시기 바랍니다.
Step 4. LocalMedia(로컬 미디어) 권한 획득하기
본격적으로 음성 채팅을 시작하기 전에, 사용자는 대화를 위한 장치가 제대로 준비되어 있는지 확인해야 합니다. 만약 장치에 이상이 있거나 장치의 접근 권한을 얻을 수 없다면, 사용자가 취해야 하는 조치(마이크 권한 허용, 카메라 권한 허용 등)를 알려주어야 합니다.
음성 채팅 서비스에서는 오디오 장치를 필수적으로 사용해야 하며, 오디오 장치 권한이 없을 경우 에러가 발생할 수 있습니다. 이 경우, 자신의 미디어인 localMedia(로컬 미디어)에 대한 확인과 try-catch를 이용한 처리가 추가로 필요합니다. 단, 오디오 장치 권한을 획득할 수 있는 웹페이지는 localhost 또는 HTTPS로 보호되는 웹 페이지어야 합니다. 충분한 보안이 없는 웹 페이지에서는 이 기능이 정상적으로 동작하지 않을 수 있습니다.
오디오와 비디오 권한 획득하기
오디오와 비디오 권한을 모두 가져오고 싶은 경우에는, 파라미터에 {audio: true, video: true}를 사용해야 합니다. 이 옵션은 getUserMedia의 constraint를 그대로 사용하고 있으며 에러 유형도 동일하게 사용합니다.
위 작업을 모두 완료 시 Room(채팅방)에 접속할 수 있으며, 해당 Room에서 발생하는 이벤트를 처리해야 합니다.
채팅방을 생성하거나 실제 카카오 i 커넥트 라이브 서버에 접속하기 위해서는 createRoom() 메서드를 사용합니다. Room이 만들어지면, Room 객체를 이용하여 특정 Room에 참가하기 전에 Room에 대한 이벤트 처리를 정의해야 합니다.
다음 예제에서는 Room에서 가장 중요한 connected, participantEntered, participantLeft 이벤트에 대한 처리를 포함합니다. connected 이벤트는 로컬 사용자가 해당 Room에 접속이 성공했을 경우 해당 room의 모든 참여자들의 목록을 처리합니다. participantEntered 이벤트는 Room에서 활동 중 추가적으로 참여한 참여자들의 참여 이벤트를 처리합니다. participantLeft는 Room에서 활동하다가 도중에 Room에서 에서 나간 참여자의 이벤트를 처리합니다. Room에 실제로 접속할 때에는 room.connect 메서드()를 사용하며, 해당 채팅방의 고유 Room 아이디(roomID)을 지정해야 해당 Room으로 접속할 수 있습니다.
Room에서 발생하는 이벤트 처리에 대한 자세한 설명은 [카카오 i 기술문서] API Reference > Event를 참고하시기 바랍니다.
publish() 메서드를 사용하여 자신의 미디어인 Local Media(로컬 미디어)를 Room에 송출합니다.
코드예제LocalMedia(로컬 미디어) 송출하기
JavaScript
room.publish([localMedia])
Step 7. 종료하기
disconnect() 메서드를 사용하여 Room에서 퇴장하고, stop() 메서드를 사용하여 카메라나 마이크를 종료합니다. 그 후,
signOut() 메서드를 사용하여 로그아웃까지 하면 모든 과정이 종료됩니다. 만약 로그아웃 이후에 다른 Room으로 입장하고 싶은 경우에는 disconnect() 메서드 호출 후 다시 connect() 메서드를 사용해야 합니다.
위 작업을 모두 완료했다면 음성 채팅 서비스를 테스트할 수 있습니다. index.html 파일로 만들었다면 해당 파일을 http-server나 기타 웹 서버등을 이용하여 접속해야 합니다. 이 서비스는 한 명 또는 하나의 장치로는 원활한 테스트가 불가합니다. 따라서 다른 사용자나 다른 장치를 사용하여 최소 2개 이상의 장치에서 함께 접속한 후 테스트를 진행하시기 바랍니다.
그림음성 채팅 샘플 예제
안내
간단한 음성 채팅 서비스 구현 외에 참여자 아이디 확인이나 화면 공유 등의 다양한 기능 구현은 기능 확장하기를 참고하시기 바랍니다.
기능 확장하기
카카오 i 커넥트 라이브 SDK 2.0은 기본 다양한 확장 기능의 구현을 지원합니다.
참여자 아이디 확인하기
카카오 i 커넥트 라이브에서는 Room에 참여하고 있는 참여자들을 participant라고 부르며, participant id는 커넥트라이브가 직접 지정한 값입니다. 따라서 실제 서비스에서 사용 시, participant id값과 실제 서비스의 사용자 id간 매핑 테이블을 별도로 관리하는 것을 권장합니다.
participant 정보는 Room에서 발생하는 이벤트에서 확인할 수 있습니다. 즉, connected 또는 participantEntered와 같은 이벤트는 이벤트 객체 내에 remoteParticipant 객체나 배열값을 가지고 있습니다. 만약 서비스가 오디오 기반의 음성 채팅 서비스가 아니라 화상회의 서비스인 경우, 이벤트에서 얻은 participant 클래스에서 참여자 아디디 뿐만 아니라 영상 스트림 정보도 확인할 수 있습니다.
코드예제참여자 아이디 확인
JavaScript
id string
audios[] Audio
videos[] Video
발화중인 참여자 확인하기
카카오 i 커넥트 라이브 서비스는 수십 명의 동시 접속자를 감당할 수 있으며, 현재 채팅방에서 말하고 있는 참여자의 정보를 확인하는 기능을 제공합니다. remoteAudioSubscribed 또는 remoteAudioUnsubscribed 이벤트를 사용하면, 현재 채팅방에서 발화 또는 발화중이지 않은 참여자 정보를 실시간으로 확인할 수 있습니다. 참여자 정보는 배열 형태로 표시되며, 참여자가 발화중인 목소리 크기(Audio Level) 순서로 나열됩니다.
화면 공유 기능이 필요한 경우, 다음 예제를 통해 화면 공유 기능을 추가할 수 있습니다. 이 예제에서는 화면 공유 버튼을 클릭하면, 해당 화면이 Room에 전달되며 전체 참여자에게 공유됩니다. 화면 공유 기능과 관련한 전체 샘플 코드는 Stackblitz 예제를 참고하시기 바랍니다.
다음을 참고하여 HTML 파일에 스크린 공유 버튼과 비디오 엘리먼트를 담을 div 2개를 추가합니다.
참여자가 화면 공유 버튼을 클릭하면 createLocalScreen() 메서드를 이용해서 미디어를 가져오고, 이것을 비디오 태그로 만들어서 HTML 문서에 삽입합니다. 그 후, Room 객체에 이전에 오디오를 넣었던 방식 그대로 publish() 메서드를 호출하여 미디어를 송출합니다.
수신자 입장에서는 크게 2가지 처리가 필요합니다. 처음 Room에 들어갔을 때 이미 방에 참여하고 있는 멤버들의 공유된 화면을 가져오기 위해 connected 이벤트를 처리해야 합니다. 또한, 새롭게 공유된 화면이 있으면 이 화면을 추가하기 위해 remoteVideoPublished 이벤트를 추가합니다.