API Reference

⚠️ SDK 2.0.x 버전과 2.1.x 이후 버전간 호환 불가

옴니톡의 이벤트 목록은 Event Message를 확인해 주세요. Omnitalk Android Demo앱 소스 코드는 이곳 에서 확인 하실 수 있습니다.

View

영상을 송출이 필요한 API는 영상을 출력할 SurfaceViewRenderer가 필요합니다. 해당 객체를 생성하기 위해서 org.webrtc 패키지를 import 해야 합니다. ( Omnitalk SDK 패키지에 포함된 모듈 )

API 호출 성공시 화면에 영상이 렌더링되기 때문에 예제에서는 CoroutineScope(Dispatchers.Main) 에서 코드를 실행 합니다. 만약 RecyclerView를 사용하려는 경우에는 onBindViewHolder 에서 sdk.bind 를 호출하여 영상을 바인딩 해주어야 합니다. 자세한 예시는 Demo를 참고 바랍니다.

Event 수신 방법

sdk.setOnEventListener 를 호출하여 이벤트 리스너를 등록 합니다. onEvent와 onClose 함수를 override하여 이벤트 메세지를 수신할 수 있습니다. 이벤트 메세지 내용은 Event Message를 참조 바랍니다.

이벤트 메세지는 Omnitalk SDK에서 제공하는 타입으로 캐스팅하여 사용할 수 있습니다. 다음은 onEvent 이벤트 처리 예시입니다. 

sdk.setOnEventListener(object : OmniEventListener {
    override fun onEvent(eventName: OmniEvent, message: Any) {
        when(eventName) {
            OmniEvent.LEAVE_EVENT -> {
                val leaveMsg = message as EventLeave
                ...
            }
            ...
        }
    }
    override fun onClose() {
        ...
    }
})

Global Module

Omnitalk sdkInit API를 통해서 객체를 초기화 합니다. 초기화 이후에는 getInstance() 를 통해서 객체를 반환 받을 수 있습니다. SDK 객체는 이후 모든 메서드 호출에 사용됩니다. Service Id와 Service Key는 console 페이지에서 발급 가능하며 노출되지 않도록 주의하여야 합니다.

import io.omnitalk.sdk.Omnitalk
...

Omnitalk.sdkInit(serviceId="YOUR_SERVICE_ID", serviceKey="YOUR_SERVICE_KEY", applicationContext=applicationContext)
val sdk = Omnitalk.getInstance()

createSession

사용자의 세션을 생성하기 위해 서버와 연결하고 그 결과로 세션 아이디, 유저 아이디 등을 포함한 CreateSessionResult 객체를 리턴합니다. userId를 null로 전달하면 임의의 ID 정보를 자동으로 할당합니다.

CoroutineScope(Dispatchers.Default).launch {
    try {
        val createSessionResult = sdk.createSession(userId="omnitalk")
    } catch (err: Exception) {
        ...
    }
}

이후 API 설명부터는 CoroutineScope(Dispatchers.Default).launch 내용을 생략합니다.

makeSipNumber

SIP 전화에 필요한 number를 생성하는 API 입니다. MakeSipNumberResult 객체를 리턴합니다.

val makeSipNumberResult = sdk.makeSipNumber(callNumber="123456", roomId=null)

sessionList(deprecated)

세션 생성 후 같은 Service Id 및 Key를 사용하는 모든 사용자를 조회하고 SessionListResult 객체를 리턴합니다.

val sessionListResult = sdk.sessionList(page: 1)

createRoom

방송할 수 있는 방을 만들고 roomId를 포함한 CreateRoomResult 객체를 리턴합니다. roomType를 제외한 나머지 인자는 Optional 입니다.

import io.omnitalk.sdk.types.PublicTypes

val createRoomResult = sdk.createRoom(
    roomType = PublicTypes.VIDEOROOM_TYPE.videoroom, 
    subject = "subject", 
    secrt = "secret", 
    startDate = null, 
    endDate = null
)

destroyRoom

생성되어 있는 방을 삭제하고 DestroyRoomResult 객체를 리턴합니다.

val destroyRoomResult = sdk.destroyRoom(roomId="ABC123=")

roomList

이미 생성된 방 목록을 조회하고 RoomListResult 객체를 리턴합니다. 방 목록 조회는 roomType별로 가능합니다.

roomType=PublicTypes.VIDEOROOM_TYPE.all 로 적용하면 모든 roomType 목록을 조회할 수 있습니다.

val roomList = sdk.roomList(roomType=PublicTypes.VIDEOROOM_TYPE.videoroom, page=1)

joinRoom

방에 참여하고 JoinRoomResult 객체를 리턴합니다. 방송을 시작하거나 다른 방송을 시청하기 위해 반드시 참여 과정을 수행해야 합니다. roomId를 제외한 나머지 인자는 Optional 입니다.

JoinRoomResult에 screen 필드는 참여한 방에 화면 공유 진행 여부를 나타냅니다.

val joinRoomResult = sdk.joinRoom(roomId=roomId, secret="secret", userName="userName")

partiList

입장한 방의 참여자 목록을 조회하고 PartiListResult 객체를 리턴합니다. roomId를 null로 전달하면 현재 참여중인 방의 참여자 목록을 조회합니다.

val partiList = sdk.partiList(roomId=nil, page=1)

publishList

입장한 방의 송출자 목록을 조회하고 PublishListResult 객체를 리턴합니다. roomId를 null로 전달하면 현재 참여중인 방의 송출자 목록을 조회합니다.

val publishListResult = sdk.publishList(roomId=nil, page=1)

screenList

입장한 방의 화면공유 목록을 조회하고 ScreenListResult 객체를 리턴합니다. roomId를 null로 전달하면 현재 참여중인 방의 화면 공유 목록을 조회합니다.

val screenListResult = sdk.screenList(roomId=nil)

publish

로컬의 영상을 송출합니다. publish API는 roomType VIDEO_ROOM 또는 WEBINAR 에서만 필요한 기능입니다.

파라미터에 로컬의 영상을 출력할 SurfaceViewRenderer 객체를 전달합니다. 해당 객체를 생성하기 위해서 org.webrtc 패키지를 import 해야 합니다. ( Omnitalk SDK 설치에 포함된 패키지 )

publish 성공시 화면에 영상이 렌더링되기 때문에 예제에서는 CoroutineScope(Dispatchers.Main) 에서 코드를 실행 합니다.

import org.webrtc.SurfaceViewRenderer

CoroutineScope(Dispatchers.Main).launch {
    try {
        val localView = findViewById<SurfaceViewRenderer>(R.id.localVideo)
        sdk.publish(localView=localView)
    } catch (err: Exception) {
        ...
    }
}

subscribe

subscribe는 roomType VIDEO_ROOM 또는 WEBINAR 에서만 필요하며, 방에 참여하면 방송 중인 송출자의 목록을 조회하고 시청할 수 있습니다. 다른 송출자의 session은 송출자 목록을 조회하면 알 수 있습니다.

subscribe의 경우 송출자의 영상을 출력할 SurfaceViewRenderer 객체가 필요합니다. 해당 객체를 생성하기 위해서 org.webrtc 패키지를 import 해야 합니다. ( Omnitalk SDK 패키지에 포함된 모듈 )

subscribe 성공시 화면에 영상이 렌더링되기 때문에 예제에서는 CoroutineScope(Dispatchers.Main) 에서 코드를 실행 합니다. 만약 RecyclerView를 사용하려는 경우에는 onBindViewHolder 에서 sdk.bind 를 호출하여 영상을 바인딩 해주어야 합니다. 자세한 예시는 Demo를 참고 바랍니다.

import org.webrtc.SurfaceViewRenderer

CoroutineScope(Dispatchers.Main).launch {
    try {
        val remoteView = findViewById<SurfaceViewRenderer>(R.id.remoteView)
        sdk.subscribe(publisherSession="PUBLISHER_SESSION", remoteView=remoteView)
    } catch (err: Exception) {
        ...
    }
}

unsubscribe

구독중인 사용자의 영상을 구독 중지하고 UnsubscribeResult 객체를 리턴합니다.

val unsubscribeResult = unsubscribe(publisherSession="PUBLISHER_SESSION")

offerCall

1:1 음성 또는 영상 발신 기능을 수행하고 OfferCallResult 객체를 리턴합니다. offerCall 호출이 성공하면 수신자는 RINGING_EVENT 를 받습니다. ( 발신자는 RINGBACK_EVENT를 수신합니다. )

callType과 calleeId는 필수값이며 녹화 여부에 대한 record는 Optional 입니다. ( 기본값 false )

⚠️ 2.1.x 이후 버전부터 record 파라메터가 삭제되었습니다. 녹음은 recordingStart 함수를 사용합니다.

callType이 VIDEO_CALL 인 경우 영상을 표현할 SurfaceViewRenderer 타입의 localView와 remoteView는 인자로 전달 해야합니다. AUDIO_CALL과 SIP_CALL 의 경우 null로 전달하시면 됩니다.

offerCall은 수신자가 존재하지 않아도 요청 가능합니다. 수신자가 RINGING_EVENT를 받지 못했을 경우 offerCall의 리턴 데이터(call_type, caller)를 수신자의 answerCall 인수로 전달하면 전화를 연결할 수 있습니다. 전체 흐름은 Call Flow에서 그림으로 확인할 수 있습니다.

import org.webrtc.SurfaceViewRenderer

val localView = findViewById<SurfaceViewRenderer>(R.id.localView)
val remoteView = findViewById<SurfaceViewRenderer>(R.id.remoteView)

// videocall의 경우
CoroutineScope(Dispatchers.Main).launch {
    try {
        val offerCallResult = sdk.offerCall(
            callType= PublicTypes.CALL_TYPE.videocall,
            callee="CALLEE_ID",
            record=true,
            localView=localView,
            remoteView=remoteView
        )
    } catch (err: Exception) {
        ...
    }
}

// audiocall의 경우
val offerCallResult = sdk.offerCall(
    callType= PublicTypes.CALL_TYPE.audiocall,
    callee: "CALLEE_ID",
    record: true,
    localView: null,
    remoteView: null)

answerCall

발신자가 offerCall을 호출하면 수신자에게는 RINGING_EVENT가 발생합니다. 수신자가 answerCall을 호출하면 전화를 연결할 수 있습니다. (이 경우에는 answerCall에 인자를 전달하지 않아도 됩니다.) 발신자와 수신자가 연결되면 CONNECTED_EVENT가 발생합니다.

offerCall은 수신자가 존재하지 않아도 요청 가능합니다. 수신자가 RINGING_EVENT를 받지 못했을 경우 offerCall의 리턴 데이터(call_type, caller)를 수신자의 answerCall 인수로 전달하면 전화를 연결할 수 있습니다. 전체 흐름은 Call Flow에서 그림으로 확인할 수 있습니다.

iOS SDK에서는 두 상황별로 API를 오버로딩하여 별도로 제공합니다. 예시는 아래와 같습니다.

// 수신자가 RINGING_EVENT를 받고 answerCall을 호출하는 경우
sdk.answerCall(localView=localView, remoteView=remoteView) // videocall
sdk.answerCall(localView=null, remoteView=null) // audiocall

// 수신자가 RINGING_EVENT를 받지 않은 경우
sdk.answerCall(callType=PublicTypes.CALL_TYPE.videocall, caller="CALLER_ID", localView=localView, remoteView=remoteView) // videocall
sdk.answerCall(callType=PublicTypes.CALL_TYPE.audiocall, caller="CALLER_ID", localView=nil, remoteView=nil) // audiocall

leave

자신의 방송을 종료합니다. 퇴장시, 다른 참가자들은 LEAVE_EVENT 를 수신 합니다. (참고: EVENT_MESSAGE )

sdk.leave()

kickOut

사용자가 룸에 참여해 방송을 개시한 이후에 다른 사용자를 강제퇴장 시키는 기능입니다. 인수로 전달하는 session은 룸에서 강제 퇴장되며 세션이 끊어지게 됩니다. 룸의 다른 참여자들에게는 KICKOUT_EVENT가 발생합니다.

sdk.kickOut(target="TARGET_SESSION")

switchCameraDevice

송출중인 카메라 장치를 변경합니다. API를 호출하면 전면 카메라와 또는 후면 카메라로 전환 됩니다.

sdk.switchCameraDevice()

setAudioDevice

송출중인 오디오 장치를 변경합니다. 인자는 MIC_TYPE으로 defaultInEar와 speaker 모드가 있습니다.

sdk.setAudioDevice(type=PublicTypes.MIC_TYPE.defaultInEar)

setMute

영상 또는 음성의 출력 상태를 mute 상태로 변경합니다. setMute 호출시 다른 참가자들에게 MUTE_EVENT 이벤트가 발생합니다.

sdk.setMute(track=PublicTypes.TRACK_TYPE.video)

setUnmute

영상 또는 음성의 출력 상태를 mute 상태로 변경합니다. setMute 호출시 다른 참가자들에게 UNMUTE_EVENT 이벤트가 발생합니다.

sdk.setUnmute(track=PublicTypes.TRACK_TYPE.video)

sendMessage

채팅 기능을 사용할 수 있는 API 입니다. 같은방에 참여한 사용자들에게는 MESSAGE_EVENT 이벤트가 발생합니다.

sdk.sendMessage(message="MESSAGE")

sendWhisper

귓속말 기능을 사용할 수 있는 API 입니다. target에 참여자 session을 전달 해야하며, 해당 session을 가진 참여자 에게만 MESSAGE_EVENT 이벤트가 발생합니다.

sdk.sendWhisper(message="MESSAGE", target="ABC123=")

messageList

입장한 방의 채팅 참여자 목록을 조회하고 MessageListResult 객체를 리턴합니다.

val messageListReulst = sdk.messageList()

sdk 2.1.x 이후 버전부터 사용 가능

recordingStart

음성 녹음을 시작하는 API입니다. 모든 call_type에서 호출할 수 있습니다. 단, 녹음 시작 API 호출은 call/room에 참여한 사용자별로 한 번만 호출할 수 있습니다. recordingStop()을 호출하지 않고 leave()를 호출 하거나 연결이 끊어져도 해당 시점까지 녹음은 마무리됩니다.

sdk.recordingStart();

recordingStop

음성 녹음을 종료하는 API입니다. 녹음 완료 시 옴니톡 콘솔에 등록한 Webhook URL로 콜백을 받을 수 있습니다.

sdk.recordingStop();

PreviousQuick StartNextDeveloper's Guide

Last updated