Documentation for WebRTC iPhone SDK | Voxeet

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

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