본문 바로가기 메뉴 바로가기

Kakao i Connect Live::Kakao i Connect Live 2.0::Quick Guide

페이지 이동경로

Quick Guide for Web

Quick Guide에서는 Web 버전의 카카오 i 커넥트 라이브 SDK 2.0을 이용하여 Web 환경에서 음성 채팅 서비스를 직접 구현하면서 SDK 기본 요소와 개념을 살펴보도록 하겠습니다.
음성 채팅 서비스는 다수의 참여자들이 한 방(Room)에 모여 이야기를 나누는 서비스입니다. 음성 채팅 서비스를 처음부터 개발하는 것은 어려운 과정일 수 있지만, 카카오 i 커넥트 라이브 SDK를 사용하면, 채팅방을 생성하고, 음성을 송출하고, 채팅방에서 발생하는 일련의 이벤트를 처리하는 것 만으로 음성 채팅 서비스를 쉽게 개발할 수 있습니다.
Quick Guide에서 SDK 기본 개념과 대략적인 개발 순서를 이해한다면, 다양한 라이브 스트리밍 서비스를 어렵지 않게 구현할 수 있을 것입니다. 기본적인 음성 채팅 서비스를 구현하는 것 외에, 발화자 확인 또는 화면 공유 기능 등 SDK가 제공하는 확장 기능을 구현하고 방법은 기능 확장하기를 참고하시기 바랍니다.

안내
음성 채팅 서비스 구현과 관련한 소스 코드는 Github Repository에서 다운로드할 수 있습니다. 또한, StackBlitz에서도 카카오 i 커넥트 라이브 음성채팅 샘플의 전체 코드를 확인할 수 있습니다.
안내
현재 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 기본 클래스

표SDK 기본 클래스
클래스 설명
participant 라이브 스트리밍 서비스의 채팅방에 참여한 참여자
Room 참여자들이 입장하는 채팅방
Media 미디어 생성 주체에 따라 다음으로 구분 됨
- LocalMedia(로컬 미디어): 자신의 미디어
- RemoteMedia(리모트 미디어): 상대방의 미디어
안내
Web 버전의 카카오 i 커넥트 라이브 SDK에서 제공하는 주요 메서드는 [카카오 i 기술문서] API 레퍼런스 > Web 문서를 참고하시기 바랍니다.

개발 흐름도

카카오 i 커넥트 라이브 SDK를 사용하여 음성 채팅을 포함한 라이브 스트리밍 서비스를 개발하는 대략적인 흐름은 다음과 같습니다. 상세한 개발 가이드는 [카카오 i 기술문서] 개발자 가이드 > Web 문서를 참고하시기 바랍니다.

Web SDK 개발 흐름 그림Web SDK 개발 흐름

  1. signIn() 메서드를 사용하여 카카오 i 커넥트 라이브에 로그인 및 인증을 수행합니다. 인증 시 카카오 i 커넥트 라이브 콘솔에서 서비스 인증 정보를 발급받아 인자로 전달해야 합니다. 인증 및 키(Key) 처리에 대한 자세한 설명은 [카카오 i 기술문서] 인증 및 키 처리 문서를 참고하시기 바랍니다.

    안내
    무료 사용자도 콘솔에 회원가입을 할 경우, 개발과 테스트를 수행할 수 있습니다. 단, 무료 계정의 경우 다음의 제약 사항이 적용됩니다.
    - 채팅방(Room)마다 최대 3분까지 테스트 가능(동일 방에서 여러 번 테스트는 가능
    - 하나의 채팅방(Room)만 개설 가능

  2. createRoom() 메서드를 사용하여 참여자들이 입장하는 채팅방(Room)을 생성합니다. Room을 생성하는 즉시 Room과 관련된 다양한 이벤트(입장/퇴장 목록, 현재 발화자 정보, 카메라 사용 여부, 영상 송출 정보 등)를 수신할 수 있습니다. 이벤트와 관련한 자세한 설명은 Event를 확인하시기 바랍니다.

  3. 자신의 미디어인 LocalMedia(로컬 미디어)를 생성합니다.

  4. publish() 메서드를 사용하여 LocalMedia를 Room에 송출합니다.

  5. 채팅방을 종료하고 로그아웃합니다.

음성 채팅 서비스 구현하기

음성 채팅 서비스는 영상 배치나 카메라 권한 허용 등의 복잡한 작업이 필요하지 않기 때문에 카카오 i 커넥트 라이브 SDK를 가장 쉬운 방식으로 사용해 볼 수 있는 예제라고 할 수 있습니다. 예제를 살펴보면서 SDK 기본 개념에서 설명한 Room(채팅방)과 LocalMedia(로컬 미디어), Participant(참여자) 클래스의 개념과 이들의 동작 관계를 살펴보도록 하겠습니다.

Step 1. 개발 환경 설정하기

Quick Guide에서는 온라인 IDE(Integrated Development Environment) 환경과 로컬 환경을 구분하여 개발 환경을 설명합니다. Stackblitz 또는 Codesandbox 등의 온라인 웹 개발 환경을 사용하는 경우 별도로 개발 환경을 설정하지 않아도 테스트가 가능합니다. 단, 로컬 방식을 사용하는 경우에는 Node.js가 실행될 수 있는 환경과 http-server 등의 정적(Static) 파일 웹서버 환경을 준비하시기 바랍니다.

온라인 IDE 환경

CodeSandbox 또는 Stackblitz와 같은 온라인 웹 개발 환경인 경우, 별도의 개발 환경을 설정할 필요가 없으며, 개발과 동시에 바로 브라우저로 디버깅 및 실행을 해볼 수 있습니다.
카카오 i 커넥트 라이브의 구현 예제는 Stackblitz 음성 채팅 샘플을 참고하시기 바랍니다.

SDK 기본 클래스 그림Stackblitz 실시간 음성 채팅 예제

Node.js 개발 환경
Node.js 개발 환경인 경우, 프로젝트에 SDK를 추가해야 합니다.

Vanilla JS 개발 환경
Vanilla JS 개발 환경인 경우, 프로젝트에 SDK를 추가하고 상세 설정을 수행해야 합니다.

안내
본 문서의 모든 소스 코드는 Github Repository에서 다운로드할 수 있습니다. 이 경우, 별도의 과정 없이 바로 git clone 명령으로 소스를 다운로드 후 http-server를 실행하여 테스트 및 학습을 수행할 수 있습니다.

Step 2. SDK 설치 및 HTML 페이지 구성하기

SDK를 이용한 웹 기반 프로젝트를 테스트하기 위해서는 먼저 웹 프로젝트를 새롭게 작성하고, HTML 파일을 새로 작성해야 합니다. 음성 채팅을 위한 HTML 화면은 영상을 배치할 필요가 없으므로, 최대한 간단하게 [연결] 버튼과 [종료] 버튼으로 구성합니다.
[연결] 버튼을 클릭 시, 즉시 특정 음성 채팅방으로 연결되어 대화할 수 있습니다. 반대로 [종료] 버튼을 클릭하면 모든 대화가 종료되고 초기화됩니다. SDK 설치 및 HTML 화면 구성 코드는 다음과 같습니다.

Web 개발 흐름 그림SDK 설치 및 HTML 화면 구성

코드예제SDK 설치 및 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 커넥트 라이브 콘솔에서 서비스 인증 정보를 발급받아 인자로 전달해야 합니다.

코드예제카카오 i 커넥트 라이브에 로그인 

    await ConnectLive.signIn({
        serviceId: '{서비스 ID}',
        serviceSecret: '{서비스 시크릿}'
    })

표signIn()_커넥트 라이브 내부 인증 Parameters
파라미터 타입 필수 여부 설명
endpoint String 선택 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로 보호되는 웹 페이지어야 합니다. 충분한 보안이 없는 웹 페이지에서는 이 기능이 정상적으로 동작하지 않을 수 있습니다.

코드예제LocalMedia(로컬 미디어) 권한 획득 

localMedia = await ConnectLive.createLocalMedia({audio: true})

Step 5. 채팅방 접속/이벤트 처리하기

위 작업을 모두 완료 시 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를 참고하시기 바랍니다.

코드예제채팅방 접속/이벤트 처리하기 

    room = await ConnectLive.createRoom()
    if (!room) {
    connectButton.innerHTML = 'failed to create room'
    throw new Error('Failed to create room')
    }
    room.on('connected', (evt) => {
    connectButton.innerHTML = 'connected'
    evt.remoteParticipants.forEach((member) => {
        console.log('user: ' + member.id + ' is entered.')
    })
    })
    room.on('participantEntered', (evt) => {
    console.log('user: ' + evt.remoteParticipant.id + ' is entered.')
    });
    room.on('participantLeft', (evt) => {
    console.log('user: ' + evt.remoteParticipantId + ' is left.')
    })
    await room.connect(roomId)

Step 6. Local Media(로컬 미디어) 송출하기

publish() 메서드를 사용하여 자신의 미디어인 Local Media(로컬 미디어)를 Room에 송출합니다.

코드예제LocalMedia(로컬 미디어) 송출하기 

room.publish([localMedia])

Step 7. 종료하기

disconnect() 메서드를 사용하여 Room에서 퇴장하고, stop() 메서드를 사용하여 카메라나 마이크를 종료합니다. 그 후, signOut() 메서드를 사용하여 로그아웃까지 하면 모든 과정이 종료됩니다.
만약 로그아웃 이후에 다른 Room으로 입장하고 싶은 경우에는 disconnect() 메서드 호출 후 다시 connect() 메서드를 사용해야 합니다.

코드예제종료하기 

room.disconnect()
localMedia.stop()
ConnectLive.signOut()

Step 8. 테스트하기

위 작업을 모두 완료했다면 음성 채팅 서비스를 테스트할 수 있습니다. index.html 파일로 만들었다면 해당 파일을 http-server나 기타 웹 서버등을 이용하여 접속해야 합니다. 이 서비스는 한 명 또는 하나의 장치로는 원활한 테스트가 불가합니다. 따라서 다른 사용자나 다른 장치를 사용하여 최소 2개 이상의 장치에서 함께 접속한 후 테스트를 진행하시기 바랍니다.

SDK 기본 클래스 그림음성 채팅 샘플 예제

안내
간단한 음성 채팅 서비스 구현 외에 참여자 아이디 확인이나 화면 공유 등의 다양한 기능 구현은 기능 확장하기를 참고하시기 바랍니다.

기능 확장하기

카카오 i 커넥트 라이브 SDK 2.0은 기본 다양한 확장 기능의 구현을 지원합니다.

참여자 아이디 확인하기

카카오 i 커넥트 라이브에서는 Room에 참여하고 있는 참여자들을 participant라고 부르며, participant id는 커넥트라이브가 직접 지정한 값입니다. 따라서 실제 서비스에서 사용 시, participant id값과 실제 서비스의 사용자 id간 매핑 테이블을 별도로 관리하는 것을 권장합니다.
participant 정보는 Room에서 발생하는 이벤트에서 확인할 수 있습니다. 즉, connected 또는 participantEntered와 같은 이벤트는 이벤트 객체 내에 remoteParticipant 객체나 배열값을 가지고 있습니다. 만약 서비스가 오디오 기반의 음성 채팅 서비스가 아니라 화상회의 서비스인 경우, 이벤트에서 얻은 participant 클래스에서 참여자 아디디 뿐만 아니라 영상 스트림 정보도 확인할 수 있습니다.

코드예제참여자 아이디 확인 

id string
audios[] Audio
videos[] Video

발화중인 참여자 확인하기

카카오 i 커넥트 라이브 서비스는 수십 명의 동시 접속자를 감당할 수 있으며, 현재 채팅방에서 말하고 있는 참여자의 정보를 확인하는 기능을 제공합니다.
remoteAudioSubscribed 또는 remoteAudioUnsubscribed 이벤트를 사용하면, 현재 채팅방에서 발화 또는 발화중이지 않은 참여자 정보를 실시간으로 확인할 수 있습니다. 참여자 정보는 배열 형태로 표시되며, 참여자가 발화중인 목소리 크기(Audio Level) 순서로 나열됩니다.

코드예제발화중인 참여자 확인 

room.on('remoteAudioSubscribed', evt => evt.participant);
room.on('remoteAudioUnsubscribed', evt => evt.participant);
room.getRemoteAudioLevels()

화면 공유 기능 추가하기

화면 공유 기능이 필요한 경우, 다음 예제를 통해 화면 공유 기능을 추가할 수 있습니다. 이 예제에서는 화면 공유 버튼을 클릭하면, 해당 화면이 Room에 전달되며 전체 참여자에게 공유됩니다. 화면 공유 기능과 관련한 전체 샘플 코드는 Stackblitz 예제를 참고하시기 바랍니다.

  1. 다음을 참고하여 HTML 파일에 스크린 공유 버튼과 비디오 엘리먼트를 담을 div 2개를 추가합니다.

    코드예제화면 공유 기능 추가 

       <body style="background-color: #f7e600">
       <div id="app"></div>
       <h1>카카오 i 커넥트 라이브 음성채팅 샘플 + 화면공유</h1>
       <button id="connectButton">Connect</button>
       <button id="disconnectButton">Disconnect</button>
       <button id="shareButton" disabled="true">Screen</button>
       <div class="local-container"></div>
       <div class="remote-container"></div>
   </body>

  2. 참여자가 화면 공유 버튼을 클릭하면 createLocalScreen() 메서드를 이용해서 미디어를 가져오고, 이것을 비디오 태그로 만들어서 HTML 문서에 삽입합니다. 그 후, Room 객체에 이전에 오디오를 넣었던 방식 그대로 publish() 메서드를 호출하여 미디어를 송출합니다.

    코드예제미디어 송출 

      const screenshare = async () => {
      screenMedia = await ConnectLive.createLocalScreen({
        audio: true,
        video: true,
      });
      const video = screenMedia.video.attach();
      document.querySelector('.local-container').appendChild(video);
      room.publish([screenMedia]);
    };

  3. 수신자 입장에서는 크게 2가지 처리가 필요합니다. 처음 Room에 들어갔을 때 이미 방에 참여하고 있는 멤버들의 공유된 화면을 가져오기 위해 connected 이벤트를 처리해야 합니다. 또한, 새롭게 공유된 화면이 있으면 이 화면을 추가하기 위해 remoteVideoPublished 이벤트를 추가합니다.

    코드예제수신자 처리 

       room.on('connected', (evt) => {
          connectButton.innerHTML = 'connected';
          if (!isMobile()) shareButton.disabled = false;
          evt.remoteParticipants.forEach(async (member) => {
            console.log('user: ' + member.id + ' is entered.');
            const unsubscribeVideos = member.getUnsubscribedVideos();
            room.subscribe([unsubscribeVideos[0].videoId]).then((remoteVideos) => {
              const video = remoteVideos[0].attach();
              document.querySelector('.remote-container').appendChild(video);
            });
          });
        });
        
        room.on('remoteVideoPublished', (evt) => {
          room.subscribe([evt.remoteVideo.videoId]).then((remoteVideos) => {
            const video = remoteVideos[0].attach();
            document.querySelector('.remote-container').appendChild(video);
          });
        });

관련 문서

Kakao i Connect Live 2.0 Kakao i Connect Live Quick Guide Kakao i Connect Live 개발자 가이드 Kakao i Connect Live API 레퍼런스 Kakao i Connect Live

이 문서가 만족스러운 이유를 알려주세요.
이 문서에 아쉬운 점을 알려주세요.
평가해주셔서 감사합니다.

더 자세한 의견은 documentation@kakaoenterprise.com 으로 제보해주세요.