API Reference

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

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

View

영상을 송출하는 videoroom, videocall의 경우 로컬의 영상을 출력할 RTCMTLVideoView가 필요합니다. 해당 객체를 생성하기 위해서 WebRTC 모듈을 import 해야 합니다. ( Omnitalk SDK 패키지에 포함된 모듈 )

Omnitalk iOS SDK는 SwiftUI를 사용하여 영상을 렌더링 합니다. OmnitalkSdk.WebRTCVideoView 을 사용하여 영상을 화면에 표현할 수 있습니다. WebRTCVIdeoView의 인자로 RTCMTLVideoView를 전달해 주시면 됩니다.

Event 수신 방법

Event를 수신할 class에서 OmnitalkSdk의 OmniEventDelegate를 채택합니다. OmniEventDelegate의 onEvent로 이벤트 메세지를 수신할 수 있습니다. 이벤트 메세지 내용은 Event Message를 참조 바랍니다.

OmniEventDeleagte protocol의 내용은 두 가지 입니다.

  • onEvent(eventName: OmniEvent, message: Any)

  • onClose()

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

import OmnitalkSdk

class Test: OmnitalkSdk.OmniEventDelegate {
    func onEvent(eventName: OmniEvent, message: Any) {
    switch eventName {
        case .LEAVE:
            let leaveEventMsg = message as! EventLeave
            ...
    }
    func onClose() {
        ...
    }
}

Global Module

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

try OmniTalk.sdkInit(serviceId: "YOUR_SERVICE_ID", serviceKey: "YOUR_SERVICE_KEY")
let sdk = OmniTalk.getInstance()

createSession

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

let createSessionResult = await sdk.createSession(userId: "omnitalk")

makeSipNumber

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

let makeSipNumberResult = await sdk.makeSipNumber(callNumber: "123456", roomId: nil)

sessionList(deprecated)

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

let sessionListResult = await sdk.sessionList(page: 1)

createRoom

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

let createRoomResult = try await sdk.createRoom(roomType: .VIDEO_ROOM, subject: "subject", secret: "secret", startDate: nil, endDate: nil)

destroyRoom

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

let destroyRoomResult = try await sdk.destroyRoom(roomId: "ABC123=")

roomList

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

roomType: .ALL 로 적용하면 모든 roomType 목록을 조회할 수 있습니다.

let roomListResult = try await sdk.roomList(roomType: .VIDEO_ROOM, page: 1)

joinRoom

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

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

let joinRoomResult = try await sdk.joinRoom(roomId: roomId, secret: "secret", userName: "userName")

partiList

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

let partiList = try await sdk.partiList(roomId: nil, page: 1)

publishList

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

let publishListResult = try await sdk.publishList(roomId: nil, page: 1)

screenList

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

let screenListResult = try await sdk.screenList(roomId: nil)

publish

방송을 개시하고 자신의 방송 번호를 포함한 PublishResult 객체를 리턴합니다. publish API는 roomType VIDEO_ROOM 또는 WEBINAR 에서 요구되는 기능입니다.

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

import WebRTC

let view = await RTCMTLVideoView()
let publishResult = try await sdk.publish(view: view)

subscribe

방송 중인 사용자의 영상을 시청합니다. subscribe API는 roomType VIDEO_ROOM 또는 WEBINAR 에서 요구되는 기능입니다. 영상을 시청하기 위한 publisherSession 정보는 publishList API를 통해 조회할 수 있습니다. subscribe()를 호출하면 상대방의 영상을 구독하고 구독 정보에 대한 SubscribeResult 객체를 리턴합니다.

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

import WebRTC

let subscribeView = await RTCMTLVideoView()
let subscribeResult = try await sdk.subscribe(publisherSession: "PUBLISHER_SESSION", view: subscribeView)

unsubscribe

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

let unsubscribeResult = try await 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 인 경우 영상을 표현할 RTCMTLVideoView 타입의 localView와 remoteView는 인자로 전달 해야합니다. AUDIO_CALL과 SIP_CALL 의 경우 nil로 전달하시면 됩니다.

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

// videocall의 경우
import WebRTC

let localView = await RTCMTLVideoView()
let remoteView = await RTCMTLVideoView()
let offerCallResult = try await sdk.offerCall(callType: .VIDEO_CALL, callee: "CALLEE_ID", record: true, localView: localView , remoteView: remoteView)

// audiocall의 경우
let offerCallResult = try await sdk.offerCall(callType: .AUDIO_CALL, callee: "CALLEE_ID", record: true, localView: nil, remoteView: nil)

answerCall

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

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

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

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


// 수신자가 RINGING_EVENT를 받지 않은 경우
try await sdk.answerCall(callType: .VIDEO_CALL, caller: "CALLER_ID", localView: localView, remoteView: remoteView) // videocall
try await sdk.answerCall(callType: .AUDIO_CALL, caller: "CALLER_ID", localView: nil, remoteView: nil) // audiocall

leave

구독중인 사용자의 방송 시청을 종료하거나 로컬의 방송을 종료합니다. leave에 종료하고 싶은 sessionId를 넘겨줍니다. sessionId를 전달하지 않는 경우 로컬의 방송이 종료됩니다.

⚠️ 2.1.x 이후 버전에서 leave는 본인의 퇴장만 가능합니다. 상대방의 강제 종료는 kickout을 사용해 주세요.

try await sdk.leave(sessionId: nil) // default: 자기 자신 퇴장

setVideoDevice

송출중인 카메라 장치를 변경합니다. 인자는 CAM_TYPE으로 front와 back 모드가 있습니다.

try await sdk.setVideoDevice(type: .front)

setAudioDevice

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

try await sdk.setAudioDevice(type: .speaker)

setMute

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

try await sdk.setMute(track: .VIDEO)

setUnmute

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

try await sdk.setUnmute(track: .VIDEO)

sendMessage

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

try await sdk.sendMessage(message: "MESSAGE")

sendWhisper

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

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

messageList

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

let messageListReulst = try await sdk.messageList()

kickOut

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

try await sdk.kickOut(target: "ABC123=")

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

recordingStart

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

try await sdk.recordingStart();

recordingStop

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

try await sdk.recordingStop();

PreviousQuick StartNextDeveloper's Guide

Last updated