Documentation for Web & Mobile WebRTC SDK

Initialize the Voxeet SDK

Two methods are currently available to initialize the SDK:

Set the API keys in the app
Use an OAuth2 server to provide the keys

`initialize`

Initialize the SDK with your Voxeet user information.

Parameters

consumerKey String - The consumer key for your app from your developer account dashboard.
consumerSecret String - The consumer secret for your app from your developer account dashboard.

Examples

import VoxeetSDK

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
        
        // Voxeet SDK initialization.
        VoxeetSDK.shared.initialize(consumerKey: "YOUR_CONSUMER_KEY", consumerSecret: "YOUR_CONSUMER_SECRET")
        
        // Example of public variables to change the conference behavior.
        VoxeetSDK.shared.pushNotification.type = .none
        VoxeetSDK.shared.conference.defaultBuiltInSpeaker = false
        VoxeetSDK.shared.conference.defaultVideo = false
        VoxeetSDK.shared.conference.audio3D = false
        
        return true
    }
}

`initialize with Oauth2`

Initialize the SDK with a valid token and a method to refresh it.

Parameters

accessToken String - A valid tokenAccess obtained from your own Oauth2 server.
refreshTokenClosure @escaping ((_ closure: @escaping (_ token: String) -> Void) -> Void) - This closure will be called when the access token needs to be refreshed from your server. Inside this one, refresh your access token and use the closure parameter to notify Voxeet of the changement: closure("token").

Example

VoxeetSDK.shared.initialize(accessToken: "YOUR_TOKEN", refreshTokenClosure: { closure in
    yourRefreshTokenMethod() { token in
        closure(token)
    }
})

`callKit`

Display the system-calling UI for your app's VoIP services.

CallKit is disabled by default. 'Push Notifications' capability needs to be enabled.

Some events can be used along with callKit to update the UI, such as VTCallKitStarted, VTCallKitSwapped, VTCallKitEnded, VTCallKitMuteToggled.

Example

VoxeetSDK.shared.pushNotification.type = .callKit
VoxeetSDK.shared.initialize(consumerKey: "YOUR_CONSUMER_KEY", consumerSecret: "YOUR_CONSUMER_SECRET")

/*
 *  MARK: - Voxeet VoIP push notifications
 *  To handle VoIP push notifications below iOS 10, you must use this AppDelegate extension:
 */

extension AppDelegate {
    /// Useful below iOS 10.
    func application(_ application: UIApplication, didReceive notification: UILocalNotification) {
        VoxeetSDK.shared.pushNotification.application(application, didReceive: notification)
    }
    
    /// Useful below iOS 10.
    func application(_ application: UIApplication, handleActionWithIdentifier identifier: String?, for notification: UILocalNotification, completionHandler: @escaping () -> Void) {
        VoxeetSDK.shared.pushNotification.application(application, handleActionWithIdentifier: identifier, for: notification, completionHandler: completionHandler)
    }
}

Session

`user`

Get current session's user (VTUser).

Example

let user = VoxeetSDK.shared.session.user

`state`

Get current session's state. VTSessionState enum: connecting, connected, reconnecting or disconnected.

Examples

let state = VoxeetSDK.shared.session.state

A delegate is also available to observe session updates:

class myClass: VTSessionDelegate {
    init() {
        VoxeetSDK.shared.session.delegate = self
    }

    func sessionUpdated(state: VTSessionState) {}
}

`connect`

This method is optional. Connect a session is like a login, however the SDK needs to be initialized with connectSession sets to false. This method can be useful if CallKit is implemented (VoIP push notifications) because once the session is openned, notifications can be received if there is an invitation.

Parameters

user VTUser? - A user to be linked to our server.
completion ((_ error: NSError?) -> Void)? - A block object to be executed when the server connection sequence ends. This block has no return value and takes a single NSError argument that indicates whether or not the connection to the server succeeded.

Example

let user = VTUser(externalID: "1234", name: "Username", avatarURL: "https://voxeet.com/logo.jpg")
VoxeetSDK.shared.session.connect(user: user) { error in }

`disconnect`

This method is optional. Close a session is like a logout, it will stop the socket and stop sending VoIP push notification.

Parameter

completion ((_ error: NSError?) -> Void)? - A block object to be executed when the server connection sequence ends. This block has no return value and takes a single NSError argument that indicates whether or not the connection to the server succeeded.

Example

VoxeetSDK.shared.session.disconnect { error in }

Conferences

`id`

Get the live conference ID (Voxeet internal identifier). If nil there is no conference going on.

Example

let conferenceID = VoxeetSDK.shared.conference.id

`alias`

Get the live conference alias. If nil there is no conference going on.

Example

let conferenceAlias = VoxeetSDK.shared.conference.alias

`users`

Get current conference users ([VTUser]).

Examples

let users = VoxeetSDK.shared.conference.users

A user can have many status before and after being connected to a conference (see VTUserConferenceStatus enum). To only get users of the live conference:

let liveUsers = VoxeetSDK.shared.conference.users.filter({ $0.asStream })

`create`

Create a conference. You can call join method if creation succeeds.

Parameters

parameters [String: Any]? - Option for passing some parameters when you create a conference, such as conferenceAlias (e.g., ["conferenceAlias": "myCustomConferenceAlias", "metadata": ["stats": false, "liveRecording": false], "params": ["videoCodec": "VP8"/"H264"]]). Those parameters are specific to a conference and should not be confused with userInfo.
success ((_ json: [String: Any]?) -> Void)? - A block object to be executed when the server connection sequence ends. This block has no return value and takes a [String: Any] argument that corresponds to a JSON dictionary object.
fail ((_ error: NSError) -> Void)? - A block object to be executed when the server connection sequence ends. This block has no return value and takes a single NSError argument that indicates whether the connection to the server succeeded.

Examples

VoxeetSDK.shared.conference.create(success: { json in
    guard let confID = json?["conferenceId"] as? String,
          let confAlias = json?["conferenceAlias"] as? String else {
        return
    }
}, fail: { error in
})

VoxeetSDK.shared.conference.create(parameters: ["conferenceAlias": "myCustomConferenceAlias", "conferenceType": "standard", "metadata": ...], success: { json in
}, fail: { error in
})

`join`

Join the created conference.

Parameters

conferenceID String - Conference identifier retrieved from create response (also compatible with conference alias).
video Bool? - Starts own video when launching the conference (false by default).
userInfo [String: Any]? - Dictionary you can use to pass additional information linked to the user. For example if the user is only in "listener" mode you can add: ["participantType": "listener"]. You can also add any data you want to set for a user: ["externalId": "1234", "externalName": "Username", "externalPhotoUrl": "https://voxeet.com/logo.jpg", ...] (if the SDK's session isn't connected yet).
success ((_ json: [String: Any]?) -> Void)? - A block object to be executed when the server connection sequence ends. This block has no return value and takes a [String: Any] argument that corresponds to a JSON dictionary object.
fail ((_ error: NSError) -> Void)? - A block object to be executed when the server connection sequence ends. This block has no return value and takes a single NSError argument that indicates whether the connection to the server succeeded.

Examples

VoxeetSDK.shared.conference.create(success: { json in
    guard let conferenceID = json?["conferenceId"] as? String else { return }
    
    VoxeetSDK.shared.conference.join(conferenceID: conferenceID, success: { json in
    }, fail: { error in
    })
    
}, fail: { error in
})

VoxeetSDK.shared.conference.join(conferenceID: conferenceID, video: true, userInfo: ["participantType": "listener"], success: { json in
}, fail: { error in
})

`leave`

Leave the current conference.

Parameter

completion ((_ error: NSError?) -> Void)? - A block object to be executed when the server connection sequence ends. This block has no return value and takes a single NSError argument that indicates whether the connection to the server succeeded.

Example

VoxeetSDK.shared.conference.leave { error in }

`status`

Retrieve the status of specified conference.

Parameters

conferenceID String - The ID of the conference whose status you want to retrieve.
success ((_ json: [String: Any]?) -> Void)? - A block object to be executed when the server connection sequence ends. This block has no return value and takes a single [String: Any]? argument that corresponds to a JSON object.
fail ((_ error: NSError) -> Void)? - A block object to be executed when the server connection sequence ends. This block has no return value and takes a single NSError argument that indicates whether the connection to the server succeeded.

Example

VoxeetSDK.shared.conference.status(conferenceID: conferenceID, success: { json in
}, fail: { error in
})

`statusSubscribe`

Subscribe to all status updates for a specified conference, such as added / removed participants and conference ended, within a notification and without joinning the conference.

The conference must be created before using this method

Parameters

conferenceID String - The ID of the conference whose status updates you want to subscribe to (also compatible with conference alias).
completion ((_ error: NSError?) -> Void)? - A block object to be executed when the server connection sequence ends. This block has no return value and takes a single NSError argument that indicates whether the connection to the server succeeded.

Example

init() {
    NotificationCenter.default.addObserver(self, selector: #selector(conferenceStatusUpdated), name: .VTConferenceStatusUpdated, object: nil)

    VoxeetSDK.shared.conference.statusSubscribe(conferenceID: conferenceID, completion: { error in })
}

@objc func conferenceStatusUpdated(_ notification: Notification) {}

`statusUnsubscribe`

Unsubscribe from status updates notifications for the specified conference.

Parameters

conferenceID String - The ID of the conference whose status events you want to unsubscribe from (also compatible with conference alias).
completion ((_ error: NSError?) -> Void)? - A block object to be executed when the server connection sequence ends. This block has no return value and takes a single NSError argument that indicates whether the connection to the server succeeded.

Example

VoxeetSDK.shared.conference.statusUnsubscribe(conferenceID: conferenceID, completion: { error in })

`localStats`

Get local WebRTC stats.

Parameter

userID String - The ID of the user whose local WebRTC stats you want to retrieve.

Returns

[[String: Any]]? - An array that contains all information in a Dictionary.

Example

let stats = VoxeetSDK.shared.conference.localStats(userID: "userID")

Record conferences

`startRecording`

Record a conference so you can replay it after it ends.

Parameters

fireInterval Int? - Useful when replaying a conference with an offset (in milliseconds). Allows the video stream to be more or less reactive depending on the length of the record. By default at 10000 milliseconds.
completion ((_ error: NSError?) -> Void)? - A block object to be executed when the server connection sequence ends. This block has no return value and takes a single NSError argument that indicates whether the connection to the server succeeded.

Example

VoxeetSDK.shared.conference.startRecording(completion: { error in })

`stopRecording`

Stop the current recording (a recording needs to be started before with startRecording method).

Parameter

completion ((_ error: NSError?) -> Void)? - A block object to be executed when the server connection sequence ends. This block has no return value and takes a single NSError argument that indicates whether the connection to the server succeeded.

Example

VoxeetSDK.shared.conference.stopRecording(completion: { error in })

Replay conferences

`replay`

Replay a recorded conference.

Parameters

conferenceID String - The ID of the conference you want to replay. Do not pass a conference alias --- pass only an ID, such as the Voxeet conference UUID returned by the join method.
offset Int? - The recording offset from the beginning of the conference. In milliseconds (default 0).
completion ((_ error: NSError?) -> Void)? - A block object to be executed when the server connection sequence ends. This block has no return value and takes a single NSError argument that indicates whether the connection to the server succeeded.

Examples

VoxeetSDK.shared.conference.replay(conferenceID: conferenceID, completion: { error in })

// Replay a conference without the first second.
VoxeetSDK.shared.conference.replay(conferenceID: conferenceID, offset: 1000, completion: { error in })

Audio and video devices

`switchDeviceSpeaker`

Switch between BuiltInSpeaker and BuiltInReceiver.

Parameter

forceBuiltInSpeaker Bool? - If true, forces the audio to set on the main speaker. If false, forces the builtInReceiver.

Examples

VoxeetSDK.shared.conference.switchDeviceSpeaker()

VoxeetSDK.shared.conference.switchDeviceSpeaker(forceBuiltInSpeaker: true)

`switchCamera`

Change the device camera (front or back).

Example

VoxeetSDK.shared.conference.switchCamera()

`mediaStream`

Get the current stream of a user.

Parameter

userID String - User ID.

Returns

MediaStream? - The stream to be rendered into the view.

Example

let stream = VoxeetSDK.shared.conference.mediaStream(userID: "userID")

`screenShareMediaStream`

Get the current screen share stream.

Returns

MediaStream? - The stream to be rendered into the view.

Example

let stream = VoxeetSDK.shared.conference.screenShareMediaStream()

`attachMediaStream`

Attach a media stream to a renderer. You can create a renderer with a UIView that inherits from VTVideoView.

Parameters

stream MediaStream - The stream to be rendered into the view.
renderer RTCVideoRenderer - The view renderer that will display the video.

Example

let stream = VoxeetSDK.shared.conference.mediaStream(userID: "userID")
let videoRenderer = VTVideoView()
VoxeetSDK.shared.conference.attachMediaStream(stream, renderer: videoRenderer)

`unattachMediaStream`

Unattach a media stream from a renderer. If you remove the video renderer from the UI, you do not need to call this method.

This method is useful for switching among several streams with the same video renderer.

Parameters

stream MediaStream - The stream to be rendered into the view.
renderer RTCVideoRenderer - The view renderer that will display the video.

Example

let stream = VoxeetSDK.shared.conference.mediaStream(userID: "userID")
let videoRenderer = VTVideoView()
VoxeetSDK.shared.conference.unattachMediaStream(stream, renderer: videoRenderer)

`startVideo`

Start the video for the specified user (typically, your own user ID). However you can't force starting or stopping a video from a specific user other than you.

Parameters

userID String? - The ID for the user whose video you want to start.
completion ((_ error: NSError?) -> Void)? - A block object to be executed when the server connection sequence ends. This block has no return value and takes a single NSError argument that indicates whether the connection to the server succeeded.

Example

VoxeetSDK.shared.conference.startVideo { error in }

`stopVideo`

Stop video for the specified user.

Parameters

userID String? - The ID for the user whose video you want to stop.
completion ((_ error: NSError?) -> Void)? - A block object to be executed when the server connection sequence ends. This block has no return value and takes a single NSError argument that indicates whether the connection to the server succeeded.

Example

VoxeetSDK.shared.conference.stopVideo { error in }

Manage users

`invite`

Invite users to a conference. Users will receive an invitationReceived event.

If callKit and push notifications are enabled, the invitation will ring on invited users' devices with the Apple incoming call user interface.

Parameters

conferenceID string - The ID of the conference you want to invite users to.
externalIDs [String] - An array of external IDs for users to invite.
completion ((_ error: NSError?) -> Void)? - A block object to be executed when the server connection sequence ends. This block has no return value and takes a single NSError argument that indicates whether the connection to the server succeeded.

Example

VoxeetSDK.shared.conference.invite(conferenceID: conferenceID, externalIDs: ["userID", ...], completion: { error in
})

`userPosition`

Set user position for the spatialized audio mode.

Parameters

userID String - The ID for the user whose position you want to set.
angle Double - The user's X position. Must be a value between -1.0 and 1.0.
distance Double - The user's Y position. Must be a value between 0.0 and 1.0.

Example

VoxeetSDK.shared.conference.userPosition(userID: "userID", angle: 0, distance: 0)

`mute`

Mute or unmute the specified user.

Parameters

userID String - The ID of the user you want to mute.
isMuted Bool - true if user is muted. Otherwise, false.

Example

VoxeetSDK.shared.conference.mute(userID: "userID", isMuted: true)

`toggleMute`

Toggle mute for the specified user.

Parameters

userID string - The ID of the user you want to mute or unmute.

Returns

Bool - The state of mute for the user.

Example

let isMuted = VoxeetSDK.shared.conference.toggleMute(userID: "userID")

`voiceLevel`

Retrieve the specified user's current audio level, normalized between 0.0 and 1.0.

Parameter

userID String - The ID of the user whose level you want to retrieve.

Returns

Double - The user's current voice level, between 0.0 and 1.0.

Example

let voiceLevel = VoxeetSDK.shared.conference.voiceLevel(userID: "userID")

Broadcast messages

`broadcast`

Broadcast messages as raw strings of any type (including JSON, XML, simple string) to all conference participants.

To receive a broadcast message, use the messageReceived method from the VTConferenceDelegate event.

Parameters

message String - The message to broadcast as a raw string.
completion ((_ error: NSError?) -> Void)? - A block object to be executed when the server connection sequence ends. This block has no return value and takes a single NSError argument that indicates whether the connection to the server succeeded.

Example

VoxeetSDK.shared.conference.broadcast(message: "message", completion: { error in })

Events

Delegates

`VTSessionDelegate`

VTSessionState enum: connecting, connected, reconnecting or disconnected.

class myClass: VTSessionDelegate {
    init() {
        VoxeetSDK.shared.session.delegate = self
    }

    func sessionUpdated(state: VTSessionState) {}
}

`VTConferenceDelegate`

class myClass: VTConferenceDelegate {
    init() {
        VoxeetSDK.shared.conference.delegate = self
    }

    func participantJoined(userID: String, stream: MediaStream) {}
    func participantUpdated(userID: String, stream: MediaStream) {}
    func participantLeft(userID: String) {}
    func messageReceived(userID: String, message: String) {}
    func screenShareStarted(userID: String, stream: MediaStream) {}
    func screenShareStopped(userID: String) {}
}

`VTConferenceCryptoDelegate`

class myClass: VTConferenceCryptoDelegate {
    init() {
        VoxeetSDK.shared.conference.cryptoDelegate = self
    }
    
    func encrypt(type: Int, ssrc: Int, frame: UnsafePointer<UInt8>, frameSize: Int, encryptedFrame: UnsafeMutablePointer<UInt8>, encryptedFrameSize: Int) {}
    func getMaxCiphertextByteSize(type: Int, size: Int) {}
    func decrypt(type: Int, ssrc: Int, encryptedFrame: UnsafePointer<UInt8>, encryptedFrameSize: Int, frame: UnsafeMutablePointer<UInt8>, frameSize: Int) {}
    func getMaxPlaintextByteSize(type: Int, size: Int) {}
}

Handling notifications

Here is an example of how to handle notifications pushed by the Voxeet SDK.

init() {
    NotificationCenter.default.addObserver(self, selector: #selector(conferenceDestroyedPush), name: .VTConferenceDestroyedPush, object: nil)
}

@objc func conferenceDestroyedPush(notification: Notification) {
    guard let userInfo = notification.userInfo?.values.first as? Data else { return }
    let json = try? JSONSerialization.jsonObject(with: userInfo, options: .mutableContainers)
}

extension Notification.Name {
    public static let VTOfferCreated = Notification.Name("OfferCreated")
    public static let VTParticipantAdded = Notification.Name("ParticipantAdded")
    public static let VTParticipantUpdated = Notification.Name("ParticipantUpdated")
    public static let VTParticipantSwitched = Notification.Name("ParticipantSwitched")
    
    public static let VTOwnConferenceCreatedEvent = Notification.Name("OwnConferenceCreatedEvent")
    public static let VTConferenceStatusUpdated = Notification.Name("ConferenceStatusUpdated")
    public static let VTConferenceDestroyedPush = Notification.Name("ConferenceDestroyedPush")
    public static let VTConferenceMessageReceived = Notification.Name("ConferenceMessageReceived")
    public static let VTOwnParticipantSwitched = Notification.Name("OwnParticipantSwitched")
    public static let VTQualityIndicators = Notification.Name("QualityIndicators")
    
    public static let VTOwnUserInvitedEvent = Notification.Name("OwnUserInvitedEvent")
    public static let VTInvitationReceivedEvent = Notification.Name("InvitationReceivedEvent")
    
    public static let VTFileSharedEvent = Notification.Name("FileSharedEvent")
    public static let VTFileConvertedEvent = Notification.Name("FileConvertedEvent")
    public static let VTFilePresentationStarted = Notification.Name("FilePresentationStarted")
    public static let VTFilePresentationUpdated = Notification.Name("FilePresentationUpdated")
    public static let VTFilePresentationStopped = Notification.Name("FilePresentationStopped")
    
    public static let VTVideoPresentationStarted = Notification.Name("VideoPresentationStarted")
    public static let VTVideoPresentationStopped = Notification.Name("VideoPresentationStopped")
    public static let VTVideoPresentationPlay = Notification.Name("VideoPresentationPlay")
    public static let VTVideoPresentationPause = Notification.Name("VideoPresentationPause")
    public static let VTVideoPresentationSeek = Notification.Name("VideoPresentationSeek")
    
    public static let VTCallKitStarted = Notification.Name("VTCallKitStarted")
    public static let VTCallKitSwapped = Notification.Name("VTCallKitSwapped")
    public static let VTCallKitEnded = Notification.Name("VTCallKitEnded")
    public static let VTCallKitMuteToggled = Notification.Name("VTCallKitMuteToggled")
}

SDK version

1.4.8

Client SDK

Documentation for WebRTC iPhone SDK | Voxeet

Initialize the Voxeet SDK

initialize

Parameters

Examples

initialize with Oauth2

Parameters

Example

callKit

Example

Session

user

Example

state

Examples

connect

Parameters

Example

disconnect

Parameter

Example

Conferences

id

Example

alias

Example

users

Examples

create

Parameters

Examples

join

Parameters

Examples

leave

Parameter

Example

status

Parameters

Example

statusSubscribe

Parameters

Example

statusUnsubscribe

Parameters

Example

localStats

Parameter

Returns

Example

Record conferences

startRecording

Parameters

Example

stopRecording

Parameter

Example

Replay conferences

replay

Parameters

Examples

Audio and video devices

switchDeviceSpeaker

Parameter

Examples

switchCamera

Example

mediaStream

Parameter

Returns

Example

screenShareMediaStream

Returns

Example

attachMediaStream

Parameters

Example

unattachMediaStream

Parameters

`initialize`

`initialize with Oauth2`

`callKit`

`user`

`state`

`connect`

`disconnect`

`id`

`alias`

`users`

`create`

`join`

`leave`

`status`

`statusSubscribe`

`statusUnsubscribe`

`localStats`

`startRecording`

`stopRecording`

`replay`

`switchDeviceSpeaker`

`switchCamera`

`mediaStream`

`screenShareMediaStream`

`attachMediaStream`

`unattachMediaStream`

`startVideo`

`stopVideo`

`invite`

`userPosition`

`mute`

`toggleMute`

`voiceLevel`

`broadcast`

`VTSessionDelegate`

`VTConferenceDelegate`

`VTConferenceCryptoDelegate`