WebRTC to WebRTC calls migration guide

Note

Before you start with the migration, you need to upgrade the InfobipRTC dependency to version 2.1.0 or newer. As before, we publish it on CocoaPods and Carthage.

callWebrtc(_ callWebrtcRequest: CallWebrtcRequest, _ webrtcCallOptions: WebrtcCallOptions) throws -> WebrtcCall

If you previously used the call method, start by migrating to the newly added callWebrtc method. Same as before, this method is used to establish calls between two WebRTC endpoints.

Arguments

The first argument changed from CallRequest to the more specific CallWebrtcRequest. Also, the second, optional, argument changed from CallOptions to WebrtcCallOptions.

Returns

The return type has changed to WebrtcCall and should be used instead of the previously available OutgoingCall. Consult the documentation of the WebrtcCall to get familiar with the newly added methods that can be used with it.

Example

• Initiate a WebRTC call with video in SDK 1.x

let token = obtainToken()
let callRequest = CallRequest(token, destination: "Alice", callDelegate: self)
let callOptions = CallOptions(video: true)
let call = InfobipRTC.call(callRequest, callOptions)

• Initiate a WebRTC call with video in SDK 2.0

let token = obtainToken()
let infobipRTC: InfobipRTC = getInfobipRTCInstance()

let callWebrtcRequest = CallWebrtcRequest(token, destination: "Alice", webrtcCallEventListener: self)
let webrtcCallOptions = WebrtcCallOptions(video: true)
let webrtcCall = infobipRTC.callWebrtc(callWebrtcRequest, webrtcCallOptions)

WebrtcCall

Deprecated Call and newly added WebrtcCall support a similar set of methods, but there are some notable changes:

• options method now returns the WebrtcCallOptions instead of the previous CallOptions
• if you previously configured RecordingOptions on your individual calls, please note that this yet not supported when migrating to RTC SDK 2.0 (for more details, consult Recording section of the migration guide)
• source and destination methods now return the Endpoint object instead of previous RTCUser
• localVideo method was renamed to cameraVideo, which lets you turn Your camera on or off.
• hasLocalVideo and hasRemoteVideo methods have been renamed to hasCameraVideo and hasRemoteCameraVideo. Also, hasRemoteScreenShare method has been added to differentiate between remote camera video and remote screen share, as the old hasRemoteVideo method returned true for any remote video track, whether it was camera or screen share.
• localVideoTrack method was split in two methods: localCameraTrack and localScreenShareTrack, which return local camera video track, and local screen share track, respectfully.
• remoteVideoTrack method was split in two methods: remoteCameraTrack and remoteScreenShareTrack, which return remote camera video track, and remote screen share track, respectfully.
• delegate field was renamed to webrtcCallEventListener and it configures WebrtcCallEventListener instead of previous CallDelegate.
• A new customData method has been introduced. It gives you access to custom data you send when making a WebRTC call. This method returns CustomData defined as an object with key-value string pairs.
• A new counterpart method has been introduced to make accessing the remote endpoint easier in your own application. It returns an Endpoint object.
• correlationId method has been removed from the new WebrtcCall
• recordingOptions method has been removed from the new WebrtcCall

WebrtcCallEventListener

There are several breaking changes concerning the configuration of the event handlers that respond to the received events. Breaking changes in context to events are caused either by an event or it's payload being changed, or a new event being introduced.

CallRingingEvent

There are no changes to the payload of the CallRingingEvent

CallEarlyMediaEvent

There are no changes to the payload of the CallEarlyMediaEvent

CallEstablishedEvent

The payload of the CallEstablishedEvent has changed. While local and remote video media was passed before, this event's payload is now empty, as the aforementioned payload is now passed through video-related events that we will mention later in this guide.

CallHangupEvent

There are no changes to the payload of the CallHangupEvent

ErrorEvent

ErrorEvent was introduced instead of the previous CallErrorEvent, and you should now use errorCode instead of the previous reason property. Note that the type of these fields stayed the same, they both provide you with an appropriate ErrorCode.

When using SDK 2.0, you may encounter Calls API error codes and WebRTC error codes.

Note that ErrorEvent event is now emitted only when a call encounters an error which does not hang up the call, unlike the case with receiving error events before.

Local and remote video events

In the SDK versions 1.x, when either side in a call turned their camera video or screen share on or off, a CallUpdatedEvent event was emitted.

With the SDK 2.0 release, a set of new events should be handled for these scenarios:

• For local video and screen share handling, you will receive the following events which you need to handle:
  • CameraVideoAddedEvent
  • CameraVideoUpdatedEvent
  • ScreenShareAddedEvent

When you remove local camera or screen share video, their respective handler will be triggered:

• onCameraVideoRemoved for removing local camera video.
• onScreenShareRemoved for removing local screen share.

• For remote video and screen share handling, you will receive the following events which you need to handle:
  • CameraVideoAddedEvent
  • ScreenShareAddedEvent

When you remove local camera or screen share video, their respective handler will be triggered:

• onRemoteCameraVideoRemoved for removing remote camera video.
• onRemoteScreenShareRemoved for removing remote screen share.

Consult the above listed links for documentation to get familiar with events and their payloads.

Note All the events should be registered with their respective handlers in Your implementation of WebrtcCallEventListener

Remote audio event handling

Among new event handling methods, there are also two new methods to handle remote audio changes:

• onRemoteMuted method is triggered when a remote endpoint becomes muted in a WebRTC call.
• onRemoteUnmuted method is triggered when a remote endpoint becomes unmuted in a WebRTC call.

Receiving a WebRTC call

In the SDK versions 1.x, you would handle incoming call by providing the handleIncomingCall method with received payload (or the same payload represented as dictionary) and getting the instance of IncomingCall object in return.

With the SDK 2.0 release, the handleIncomingCall method is expecting the IncomingCallEventListener as the second parameter to be provided besides the payload.

• For handling incoming WebRTC call, you will receive the following event which you need to handle:
  • IncomingWebrtcCallEvent

Consult the above listed links for documentation to get familiar with events and their payloads.

• Receiving a WebRTC call in SDK 1.x

func pushRegistry(_ registry: PKPushRegistry, didReceiveIncomingPushWith payload: PKPushPayload, for type: PKPushType) {
    if type == .voIP {
        os_log("Received VoIP Push Notification %@", payload.dictionaryPayload)
        if InfobipRTC.isIncomingCall(payload) {
          if let incomingCall = InfobipRTC.handleIncomingCall(payload) {
              incomingCall.accept() // or incomingCall.decline()
          }
       }   
    }
}

• Receiving a WebRTC call in SDK 2.0

let infobipRTC: InfobipRTC = getInfobipRTCInstance()
func pushRegistry(_ registry: PKPushRegistry, didReceiveIncomingPushWith payload: PKPushPayload, for type: PKPushType) {
    if type == .voIP {
        os_log("Received VoIP Push Notification %@", payload.dictionaryPayload)
        if infobipRTC.isIncomingCall(payload) {
            infobipRTC.handleIncomingCall(payload, incomingCallEventListener: self)
        }
    }
}

func onIncomingWebrtcCall(incomingWebrtcCallEvent: IncomingWebrtcCallEvent) {
    let incomingWebrtcCall = incomingWebrtcCallEvent.incomingWebrtcCall
    incomingWebrtcCall.accept() // or incomingWebrtcCall.decline()
}

Recording

If you already have Recording add-on enabled on account level, you can set the recording preferences under Channels & Numbers > WebRTC > Recording or control it via ALWAYS, ON_DEMAND and DISABLED recording flag when generating the token for the session.

When ON_DEMAND flag is used, RecordingOptions should be passed via WebrtcCallOptions. Note that RecordingOptions are different from the previously available RecordingOptions (1.x).

To determine the expected behaviour when combining any of these three elements, consult the Outcome of the recording table.

To access recording files, use the available API or Portal, passing call identifier as the callId parameter.