그룹 영상 통화 시작하기
WebPlanetKit을 사용하면 1대1 통화 또는 그룹 통화를 위한 음성 및 영상 통화 기능을 앱에 연동할 수 있습니다. 이 가이드에서는 웹 앱에서 그룹 영상 통화 구현을 시작하는 방법을 설명합니다.
더욱 빠른 개발을 위해 빠른 시작을 기반으로 앱을 구현할 수 있습니다.
필수 조건
- 사용 중인 시스템이 시스템 요구사항을 충족하는지 확인하세요.
- API key를 생성하세요. 자세한 내용은 개발 환경을 참조하세요.
- 액세스 토큰을 생성하는 앱 서버 코드를 구현하세요. 자세한 내용은 액세스 토큰 생성 방법을 참조하세요.
- Node.js를 설치하세요.
- 현재 지원하는 웹 브라우저의 사양은 다음과 같습니다. 필요한 경우 웹 브라우저를 설치하거나 버전을 업그레이드하세요.
- Chromium 72+ 기반 브라우저
- Safari 16.4+ (베타)
SDK 설치
WebPlanetKit SDK는 두 가지 방법으로 설치할 수 있습니다.
WebPlanetKit은 개발 환경에 따라 다른 라이브러리 파일을 사용합니다. 시험용(evaluation) 환경에서는 planetKit.eval.js, 실제 서비스용(real) 환경에서는 planetKit.js를 사용하세요.
npm 혹은 yarn으로 설치하기
아래와 같은 방법으로 npm 혹은 Yarn을 이용해 SDK를 설치하세요.
# npm
npm install @line/planet-kit
# yarn
yarn add @line/planet-kit
설치 완료 후 사용하려는 환경에 따라 아래와 같이 SDK를 사용하세요.
-
실제 서비스용 환경
import * as PlanetKit from "@line/planet-kit"; -
시험용 환경
import * as PlanetKit from "@line/planet-kit/dist/planet-kit-eval";
Git에서 내려받아 <script> 태그로 포함하기
npm 혹은 Yarn으로 설치하는 대신 Git 저장소의 dist 디렉터리에서 내려받은 후 <script> 태그를 사용해 WebPlanetKit SDK를 코드에 직접 포함하는 방법으로도 사용할 수 있습니다.
각 환경에 맞게 파일을 내려받은 뒤 아래와 같이 <script> 태그를 이용해 SDK를 코드에 포함합니다.
-
실제 서비스용 환경
<script type="text/javascript" src="path/to/js/planet-kit.js"></script> -
시험용 환경
<script type="text/javascript" src="path/to/js/planet-kit-eval.js"></script>
위와 같이 추가한 뒤 다음과 같이 사용합니다.
<script type="text/javascript">
const planetKit = new PlanetKit.Conference();
</script>
SDK 초기화
WebPlanetKit API를 호출하려면 먼저 SDK를 초기화해야 합니다. WebPlanetKit은 1대1 통화용과 그룹 통화(컨퍼런스)용의 두 가지 인스턴스를 갖습니다. 각 인스턴스는 설정 정보를 인자로 PlanetKit.Call()과 PlanetKit.Conference()를 호출해서 생성하며 이때 적절한 로그 수준도 함께 설정할 수 있습니다.
그룹 통화를 위해서 아래와 같이 SDK를 초기화하세요.
import * as PlanetKit from "@line/planet-kit";
const config = {
logLevel: 'log'
}
const planetKit = new PlanetKit.Conference(config);
액세스 토큰 획득
클라이언트 앱에서 앱 서버에 액세스 토큰 생성을 요청해 받으세요.
액세스 토큰은 이후 그룹 영상 통화에 참여하기 위해 joinConference()를 호출할 때마다 새로 받아서 사용해야 합니다.
그룹 영상 통화 참여
그룹 영상 통화에 참여하려면 다음 인자와 함께 joinConference()를 호출하세요.
- 아래 속성을 포함하는
ConferenceParams객체myId: 로컬 사용자의 사용자 IDmyServiceId: 로컬 사용자의 서비스 IDroomId: 방 IDroomServiceId: 방의 서비스 IDaccessToken: 액세스 토큰mediaType:'video'mediaHtmlElement: 재생할 미디어의 DOM 엘리먼트myVideo: 영상이 재생될<video>요소roomAudio: 음성이 재생될<audio>요소
delegate:ConferenceDelegate를 채택하고 준수하는 이벤트 대리자(delegate)evtConnected: 통화가 연결됐을 때 발생하는 이벤트evtDisconnected: 통화 연결이 종료됐을 때 발생하는 이벤트evtPeerListUpdated: 피어가 방에 들어오거나 나갔을 때 발생하는 이벤트evtPeersVideoUpdated: 피어의 비디오가 활성화 또는 비활성화될 때 발생하는 이벤트
<!-- Example of media elements for group video call -->
<html>
<div>
<video id="my-video" muted autoplay playsinline></video>
<audio id="room-audio" autoplay></audio>
</div>
</html>
<script>
const myVideoElement = document.getElementById('my-video');
const roomAudioElement = document.getElementById('room-audio');
</script>
/* Prepares a conferenceParams */
const onEvtConnected = () => {
// This is called when the call is connected.
// Write your own code here.
};
const onEvtDisconnected = (disconnectedParam) => {
// This is called when the call is disconnected.
// Write your own code here.
};
const onEvtPeerListUpdated = (conferencePeerUpdatedParam) => {
// This is called when the list of peers is updated.
// Write your own code here.
};
const onEvtPeersVideoUpdated = (peersVideoUpdatedParam) => {
// Triggered when the video status of one or more peers are changed.
// Write your own code here.
};
const conferenceParams = {
myId: 'MY_ID',
myServiceId: 'MY_SERVICE_ID',
roomId: 'ROOM_ID',
roomServiceId: 'ROOM_SERVICE_ID',
accessToken: 'ACCESS_TOKEN',
mediaType: 'video',
mediaHtmlElement: {
myVideo: myVideoElement,
roomAudio: roomAudioElement
},
delegate: {
evtConnected: onEvtConnected,
evtDisconnected: onEvtDisconnected,
evtPeerListUpdated: onEvtPeerListUpdated,
evtPeersVideoUpdated: onEvtPeersVideoUpdated
}
};
/* Joins conference */
planetKit.joinConference(conferenceParams)
.then(() => {
// Successfully joined a conference.
})
.catch((joinConferenceError) => {
// Failed to join a conference.
// joinConferenceError.reason: START_FAIL_REASON
// joinConferenceError.message: A descriptive message about the failure.
});
- 사용자가 클라이언트 앱에서 그룹 통화 방에 입장하려면 방 ID가 필요하므로, 애플리케이션에서 정의한 통신 채널을 통해 방 ID를 다른 사용자와 공유해야 합니다.
- 통화 연결 시 웹 브라우저에서 마이크와 카메라 권한을 요청하는 팝업 창이 표시되며, 권한을 허용해야 통화가 가능합니다.
피어 비디오 요청 및 제거
피어의 비디오를 요청하려면 ConferenceRequestPeerVideoParams를 인자로 requestPeerVideo를 호출하세요. 요청한 피어의 비디오를 제거하려면 userId를 인자로 removePeerVideo를 호출하세요.
아래 예제는 피어가 방에 입장하거나 퇴장하면서 이벤트가 발생했을 때 이벤트 핸들러에서 피어의 비디오를 요청하거나 제거하는 예제입니다.
<!-- Example of peer's video element -->
<html>
<div>
<video id="peer-video-1" muted autoplay playsinline></video>
</div>
</html>
function requestPeerVideo(userId) {
const requestPeerVideoParams = {
userId: userId,
resolution: 'vga',
videoViewElement: document.getElementById('peer-video-1')
};
planetKit.requestPeerVideo(requestPeerVideoParams)
.then(() => {
// Peer video requested successfully.
})
.catch((error) => {
// Failed to request peer video.
});
}
function removePeerVideo(userId) {
planetKit.removePeerVideo(userId)
.then(() => {
// Peer video removed successfully.
})
.catch((error) => {
// Failed to remove peer video.
});
}
// Called when the list of peers is updated.
// This handler is registered as the delegate of conferenceParams.
const onEvtPeerListUpdated = (conferencePeerUpdatedParam) => {
const { addedPeers, removedPeers } = conferencePeerUpdatedParam;
// Request video for newly added peers.
addedPeers.forEach((peerInfo) => {
if (peerInfo.videoState === VIDEO_STATE.ENABLED) {
requestPeerVideo(peerInfo.userId);
}
});
// Remove video for peers that left.
removedPeers.forEach((peerInfo) => {
if (peerInfo.isVideoRequested) {
removePeerVideo(peerInfo.userId);
}
});
};
다음 단계
아래 문서를 참조해 WebPlanetKit에서 제공하는 다양한 기능과 각 기능의 사용 방법을 자세히 살펴보세요.