Kakao i Connect Live::Connect Live SDK::Web SDK::Callback & Config

페이지 이동경로

Callback

Web 버전의 Kakao i Connect Live SDK에서 제공하는 Callback 메서드는 다음과 같습니다.

공통

일대일 통화, 방송, 그룹 통화에서 공통적으로 사용되는 Callback 메서드는 다음과 같습니다.

onInit()

onInit() Callback 메서드는 SDK가 Kakao i Connect Live 서버에 정상적으로 접속하여 방송 또는 통신 인프라를 사용할 준비가 완료되었을 때 호출됩니다. onInit() 메서드는 일반적인 경우에는 사용되지 않으며, 디버깅(Debugging) 용도로만 사용됩니다.

코드예제onInit() Syntax

const listener = {
  onInit() {
  ...   // 서비스에 맞게 구현
  }
}

onClose()

onClose() Callback 메서드는 사용자 또는 상대방이 명시적으로 close() 메서드를 호출하거나, 네트워크 이상 등으로 연결이 종료될 때 호출됩니다. onClose() Callback이 호출되면 Remon 클래스에서 사용했던 모든 자원들의 연결이 해제됩니다.

코드예제onClose() Syntax

const listener = {
  onClose() {
  ...   // 서비스에 맞게 구현
  } 
}

onError()

onError() Callback 메서드는 Remon 클래스 동작 중 에러가 발생했을 때 호출됩니다.

코드예제onError() Syntax

const listener = {
  onError(error) {
  ...   // 서비스에 맞게 구현
  }
}

onStat()

사용자는 간혹 자신 또는 상대방의 네트워크 문제로 인하여 통화 품질이 안 좋거나 끊어진 상황에서도 네트워크 문제가 아닌 서비스 문제라고 생각하고 불만을 제기할 수 있습니다. 해당 경우에는 사용자에게 서비스 문제가 아닌 네트워크 문제임을 사전에 알려주거나 또는 다양한 UI 처리를 통해 정확한 안내를 하는 것이 좋습니다.

네트워크 상황 등에 따른 미디어 품질 문제를 정확하게 파악하기 위해서는 onState(report) Callback 메서드를 통해 통화 또는 방송 상태를 알 수 있는 report를 수신할 수 있습니다. report는 사용자가 remon 클래스 생성 시에 설정한 statInterval 간격을 기준으로 제공됩니다. 해당 report는 네트워크 상황과 같은 미디어 품질을 나타내기 때문에 사용자에게 로딩 UI 처리 등을 안내하는 경우에 유용하게 사용할 수 있습니다. report에 들어오는 값은 현재 통화 품질(음성 또는 영상)에 대해 다음과 같이 총 다섯 단계로 구분되어 표시됩니다. 현재 이러한 통화 품질 정보는 5초에 한 번씩 받을 수 있으며, result에서 받을 수 있는 여러 정보 중 result.rating은 네트워크 상황에 따른 통합적인 통화 품질 정보를 의미합니다.

방송 또는 통화 품질 상태
단계 품질
1 매우 좋은 상태
2 좋은 상태
3 나쁜 상태
4 매우 나쁜 상태
5 방송 또는 통화가 불가능한 상태

코드예제onStat() Syntax

const listener = {
 onStat(result){
   const stat = `State: l.cand: ${result.localCandidate} /r.cand: ${result.remoteCandidate} /l.res: ${result.localFrameWidth} x ${result.localFrameHeight} /r.res: ${result.remoteFrameWidth} ${result.remoteFrameHeight} /l.rate: ${result.localFrameRate} /r.rate: ${result.remoteFrameRate} / Health: ${result.rating}`
   console.log(stat)
 }
}

방송

방송 서비스에서 제공하는 Callback 메서드는 다음과 같습니다.

onCreate()

onCreate() Callback 메서드는 방송 Caster에게만 사용되며, Caster는 create() 메서드를 통해 방송을 정상적으로 생성하고 송출합니다. onCreate() 메서드는 고유 구분자인 Channel ID를 생성하며, Viewer는 해당 Channel ID를 사용하여 방송에 접속할 수 있습니다.

코드예제onCreate() Syntax

const listener = {
  onCreate(channelId) {
  ...   // 서비스에 맞게 구현
  }
}

const cast = new Remon({ listener })
cast.createCast()

onCreate() Elements
구분 타입 필수 여부 설명
channelld String 선택 Caster가 생성한 방송의 고유 아이디
- Channel ID 생성 규칙에 따라 생성할 수 있으며, 미지정 시 자동 생성됨

onJoin()

onJoin() Callback 메서드는 방송에 Viewer에게만 사용하며, Viewer가 join() 메서드의 Channel ID를 통해 연결이 완료되어 미디어 시청이 가능한 상태가 되면 호출됩니다.

코드예제onJoin() Syntax

const listener = {
  onJoin(channelId) {
  ...   // 서비스에 맞게 구현
  }
}

const cast = new Remon({ listener })
cast.joinCast('{CHANNEL_ID}')

onJoin() 메서드 Elements
구분 타입 필수 여부 설명
CHANNEL_ID String 필수 Caster가 생성한 방송의 고유 아이디
- Viewer는 해당 Channel ID를 사용하여 방송에 접속

통화

통화 서비스에서 제공하는 Callback 메서드는 다음과 같습니다.

onConnect()

onConnect() Callback 메서드는 통화에서만 사용됩니다. 채널을 생성하여 통화를 요청하는 Caller와 해당 채널에 접속하여 요청에 응답하는 Callee의 동작이 다른 경우가 많기 때문에, 개발자는 Caller 또는 Callee 여부에 대한 상태를 관리에 주의해야 합니다.

  • Caller는 connect() 메서드를 통해 채널을 새로 만들고, 상대방의 입장을 기다립니다.
  • Callee는 connect() 메서드를 통해 이미 만들어진 채널에 Channel ID 정보를 가지고 접속합니다.
    • Callee가 정상적으로 채널에 연결되면 onConnect() 메서드가 호출되지만, 곧바로 발생하는 onComplete() 메서드를 사용하는 것을 권장합니다.

코드예제onConnect() Syntax

const listener = {
 onConnect(channelId) {
  if (isCaller) {
     ...   // 서비스에 맞게 구현
     }
  }
}

const call = new Remon({ listener })
call.connectCall('{CHANNEL_ID}')

onConnect() Elements
구분 타입 필수 여부 설명
channelld String 선택 Caster가 생성한 통화의 고유 아이디
- Channel ID 생성 규칙에 따라 생성할 수 있으며, 미지정 시 자동 생성됨

onComplete()

onComplete() Callback 메서드는 통화에서만 사용되며, Caller와 Callee가 연결이 완료되어 미디어 전송이 가능한 상태가 되면 호출됩니다.

코드예제onComplete() Syntax

const listener = {
  onComplete() {
  ...   // 서비스에 맞게 구현
  }
}

Config

Kakao i Connect Live SDK는 Remon 객체에 직접 설정 정보를 지정할 수 있습니다. 이러한 설정 정보를 별도의 객체에 생성해 두고, Remon 객체를 생성할 때마다 해당 설정값을 사용하고자 하거나 또는 다른 화면에서 설정값을 방송 또는 통신 화면으로 전달해야하는 경우에 Config 값을 사용할 수 있습니다.

View 설정

영상이 표출될 View를 지정하는 설정입니다. View 설정을 하지 않으면 영상이 보이지 않습니다.

코드예제View 지정

<video id="remoteVideo" autoplay controls></video>
<video id="localVideo" autoplay controls muted></video>
<script>
  const config = {
     view: {
     remote: '#remoteVideo', local: '#localVideo'
     }
  }
</script>

View 설정
속성명 필수 여부 설명
autoplay 로컬: 필수
리모트: 필수
영상을 자동으로 재생할지에 대한 여부 지정 가능
- 해당 속성이 없으면 명시적인 play()를 호출해야함
muted 로컬: 필수
리모트: 선택
음소거로 설정할지에 대한 여부 지정 가능
- Local Video의 경우에는 필수로 지정
- 자신의 음성이 다시 자기에게 들리는 하울링(Howling) 현상을 방지함
controls 로컬: 선택
리모트: 선택
속성을 명시하여 제어 기능 추가 가능

영상 활성 여부 설정

자신과 상대방 영상을 활성화 또는 비활성으로 설정할 수 있습니다. 비활성으로 설정 시, 영상은 빈 프레임으로 출력되어 검은색 화면으로 표시됩니다.

코드예제영상 활성 여부 설정

remon.pauseLocalVideo(bool)       // true로 설정 시 자신의 영상을 검은색으로 표시
remon.pauseRemoteVideo(bool)    // true로 설정 시 상대방의 영상을 검은색으로 표시 

음성 활성 여부 설정

자신 또는 상대방 음성을 활성화 또는 비활성으로 설정할 수 있습니다. 비활성으로 설정 시 음소거(mute)가 적용됩니다.

코드예제음성 활성 여부 설정

remon.muteLocalAudio(bool)        // true로 설정 시 자신의 음성을 음소거
remon.muteRemoteAudio(bool)     // true로 설정 시 상대방의 음성을 음소거

Media

음성 방송/통화 설정

비디오를 사용하지 않고, 음성 방송 또는 음성 통화 서비스를 만들 수 있습니다.

코드예제음성 방송/통화 설정

// 비디오를 사용하지 않고 음성만 사용 시 
const config = {
 media: {
   audio: true,
   video: false // false로 설정 시 비디오를 사용하지 않음
 }
}

// 비디오와 오디오를 모두 사용 시
const config = {
 media: {
   audio: true,
   video: true
 }
}

비디오 옵션 설정

WebRTC는 기본적으로 네트워크나 단말의 상태에 따라 해상도와 Frame Rate 등을 유연하게 변화시키면서 품질을 유지합니다. 따라서 해상도를 특정값으로 설정하더라도 설정된 해상도가 정확하게 유지되지 않을 수 있습니다. 이러한 경우에는 코덱 등의 옵션을 변경하여 해상도를 최적으로 설정할 수 있습니다.

코드예제비디오 옵션 설정

const config = {
 media: {
   video: {
     width: {max: '640', min: '640'},
     height: {max: '480', min: '480'},
     codec: 'H264',
     frameRate: {max:15, min:15},
     facingMode: 'user',
     maxBandwidth: '3000'
   }
 }
}

비디오 옵션 Elements
파라미터 타입 필수 여부 설명
Object 필수 비디오 옵션
width String 선택 상대에게 보낼 영상의 가로 해상도
max: 영상의 가로 최대값
min: 영상의 가로 최소값
height String 선택 상대에게 보낼 영상의 높이 해상도
max: 영상의 높이 최대값
min: 영상의 높이 최소값
codec String 선택 브라우저에서 지원하는 코덱으로, 필요 시 다른 코덱으로 변경 필요
H.264(기본값)
VP8
VP9
frameRate Integer 선택 1초에 몇 번의 프레임으로 인코딩할지 설정
- 일반적인 영상 통화에서는 15 정도가 적당도
facingMode String 선택 Mobile 기기의 앞과 뒤에 카메라가 있을 때 사용할 카메라를 설정
- 모바일 버전의 Chrome 브라우저 제외
user: 모바일의 앞에 있는 카메라를 사용
environment: 모바일의 뒤에 있는 카메라를 사용
maxBandwidth String 선택 해당 비디오의 대여폭을 설정
- 앱의 전체적인 네트워크 트래픽을 고려하여 적절한 값을 설정 필요

오디오 타입 설정

오디오 출력 시 주변 소음을 제거하는 기능과 관련한 작동 유형을 설정할 수 있습니다.

코드예제오디오 타입 설정

let config = {
   media: {},
   rtc: {audioType: "music"}
};

오디오 타입 Elements
파라미터 타입 필수 여부 설명
audioType String 선택 오디오 타입 설정
music: 모든 소리를 가공없이 전달
voice(기본값): 주변 소음을 제거하고 음성을 전달
- 통화에 적합

오디오 추가 설정

오디오에 다양한 세부 항목을 추가로 설정할 수 있습니다. 오디오 추가 설정 항목은 방송 또는 통화 환경과 목적에 따라 최적의 설정이 다를 수 있으므로, 설정 항목들을 적절히 조합하여 사용하시기 바랍니다.

코드예제오디오 추가 설정

let config = {
 media: {
   audio: {
     channelCount: 2,
     maxBandwidth: 128,
     autoGainControl: false,
     echoCancellation: false,
     noiseSuppression: false,
   }
 },
 rtc: {
   audioType: "music"
 }
};

오디오 추가 설정 Elements
파라미터 타입 필수 여부 설명
Object 선택 오디오 추가 설정
channelCount Integer 선택 오디오 채널을 설정
1: 모노(모든 소리가 한 방향에서 출력)
2: 스테레오(소리가 좌우 분리되어 출력)
maxBandwidth Integer 선택 오디오의 최대 대역폭 설정
autoGainControl Boolean 선택 자동 이득 조절(Automatic Gain Control) 설정
- 강한 레벨의 신호는 약하게, 약한 레벨의 신호는 강하게 조절
true: 자동 이득 조절을 설정
false: 자동 이득 조절을 미설정
echoCancellation Boolean 선택 통화 중 에코를 제거
true: 에코를 제거
false: 에코를 제거하지 않음
noiseSuppression Boolean 선택 통화 중 노이즈를 제거
true: 노이즈를 제거
false: 노이즈를 제거하지 않음

Debug

Debug(디버그) 레벨을 설정하여 WebRTC의 세부적인 로그를 출력할 수 있습니다. 해당 레벨 모드는 RemonConfig를 사용하여 통화 또는 방송을 생성하는 경우에만 가능합니다. VERBOSE 로그 레벨로 갈수록 더욱 자세한 내용을 확인할 수 있습니다.

코드예제Debug Syntax

const config = {
 dev:{
   logLevel: 'INFO' // SILENT, ERROR, WARN, INFO, DEBUG, VERBOSE 순으로 로그 레벨을 설정
 }
}

로그 레벨
구분 설명
SILENT 로그를 출력하지 않음
ERROR 오류를 일으킨 문제뿐만 아니라 더 낮은 레벨의 메시지도 목록에 출력
WARN 아직 오류는 아니지만 발생할 수 있는 경고성 로그와 더 낮은 레벨(ERROR)의 메시지도 목록에 출력
INFO 예상할 수 있는 진행사항 또는 상태 정보 이상의 로그와 더 낮은 레벨(WARN, ERROR)의 메시지도 목록에 출력
DEBUG 개발 단계에서만 유용한 디버그 로그와 더 낮은 레벨(INFO, WARN, ERROR)의 메시지도 목록에 출력
VERBOSE 모든 로그의 메시지 출력
이 문서가 만족스러운 이유를 알려주세요.
이 문서에 아쉬운 점을 알려주세요.
평가해주셔서 감사합니다.

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