iOS SDK

Overview

The iOS SDK lets you use Vonage Video API-powered video sessions in apps built for iPad, iPhone, and iPod touch devices.

The Vonage Video API iOS SDK reference can be found here.

Important notes:

Version 2.29.0+ of the SDK supports iOS 15 or higher
Changes to iOS 14 networking affecting relayed sessions — see the list of known issues in the release notes
Issues using Simulator to preview your app on a Mac with an M1 chip - see the list of known issues in the release notes

All applications that use the Vonage Video API are composed of two parts:

The client side, which uses the Vonage Video client SDKs and runs in a user’s browser or mobile app
The server side, which uses the Vonage Video server SDKs and runs on your server to pass authentication information to the client

The iOS client SDK provides provides most of the core functionality for your app, including:

Connecting to session
Publishing streams to a session
Subscribing to streams in a session

Client SDKs are also available for web, Android, iOS, Windows, macOS, Linux, and React Native. All client SDKs can interact with one another.

You can learn more about the basics of clients, servers, sessions, and more on the Video API Basics page.

Learning to build with the iOS SDK

The best way to learn how to use the iOS SDK is to follow the Basic Video Chat Tutorial.

Once you understand the basics of building with the Vonage iOS SDK, you can get more detailed information and learn how to customize your application with the Vonage developer guides. To investigate specific API classes and methods, see the Vonage iOS SDK API reference guide.

Interoperability

Apps written with the Vonage iOS SDK 2.32.0 can interoperate with Vonage apps written with version 2.30+ of the Vonage client SDKs:

Web SDK (OpenTok.js)
Android SDK
Windows SDK
macOS SDK
Linux SDK
React Native SDK

Client SDKs are also available for web, Android, Windows, macOS, Linux, and React Native. All Client SDKs can interact with one another. You can learn more about the basics of Vonage Video clients, servers, sessions, and more on the Video API Basics page.

Using the SDK

The iOS SDK is available as the CocoaPods Pod OTXCFramework, which is distributed as an XCFramework. If you can not use an XCFramework, the OpenTok pod was distributed as a Universal FAT framework but no longer receives updates. The iOS SDK is also available as a Swift Package Manager package, VonageClientSDKVideo. You can install the package by adding the https://github.com/vonage/vonage-video-client-sdk-swift.git repository as a Swift Package Dependency.

The current version of the iOS SDK requires Xcode 10 or higher. The iOS SDK requires the following frameworks and libraries:

AudioToolbox.framework
AVFoundation.framework
CoreGraphics.framework
CoreMedia.framework
CoreTelephony.framework
CoreVideo.framework
Foundation.framework
GLKit.framework
libc++.tbd (libc++.dylib prior to Xcode 7)
libsqlite3++.tbd (libsqlite3.dylib prior to Xcode 7)
Metal.framework
MetalKit.framework
MetalPerformanceShaders.framework
OpenGLES.framework
QuartzCore.framework
SystemConfiguration.framework
UIKit.framework
VideoToolbox.framework

Use the -force_load linker flag to load specific libraries that require it, this is handled for you if you are adding the SDK via CocoaPods or Swift Package Manager.

The iOS SDK links to the libc++ standard library. If another library that links to the libc++ standard library was compiled in a version of Xcode older than 6.0.0, it may result in segfaults at run time when using it with the iOS SDK. Known incompatible libraries include, but are not limited to, Firebase (versions earlier than 2.1.2 -- see https://code.google.com/p/webrtc/issues/detail?id=3992 and Google Maps (versions earlier than 1.9.0). To fix this issue, download a version of the other library that was compiled using Xcode 6.0.0 or later. See the release notes for information on the latest version of the SDK and for a list of known issues.

In order to access the camera and microphone, iOS 10 requires you to set values for the NSCameraUsageDescription and NSMicrophoneUsageDescription keys in the Info.plist file. These define strings that appear in the app installer to inform the user why your app uses the camera and microphone.

For more information see the Apple documentation on Cocoa keys.

See this document for information on using the SDK in apps running in the background mode.

Privacy manifest settings

Version 2.25.5 and newer of the SDK has support for the privacy manifest required by Apple's App store. Using these versions of the SDK, the required privacy-related settings are automatically added when you create your app's privacy report. If you need to use an older version of the SDK, you can manually add the required privacy settings based on the settings in this file to your app's privacy manifest file.

CallKit

CallKit is a framework that lets iOS apps improve their integration with the OS, allowing the app to:

Notify about incoming or outgoing calls to the OS
Launch the app with a VoIP push notification (only if you want to show the incoming call UI)
Handle audio routing
Coordinate the audio sessions between all ongoing apps
Boost audio output levels
Display call controls in a notification and a native call UI

Vonage video provides two ways of integrating with CallKit:

Set up a CustomAudioDevice that controls the AudioSession activations. See this sample.
Activate the calling services mode using OTAudioDeviceManager.currentAudioSessionManager(). The instance returned from the audio session manager should be used for configuring the audio session and notifying the SDK about audio session activations and deactivations. See this sample.

If your app needs to be notified for application events, such as incoming calls, the developer is responsible for implementing it. We recommend using the PushKit framework and VoIP push notifications. As a reference, see this sample.

The native Vonage Video integration requires that the developer enables the calling services mode early in the app launch. VoIP push notifications require a call to CXProvider.reportNewIncomingCall within 3 seconds; otherwise, the app can crash. In that timeframe, the app should configure the SDK CallKit support before the CXAnswerCallAction callback is executed.

To enable the calling services mode, call the following code in your app's application:didFinishLaunchingWithOptions: method.

let sessionManager = OTAudioDeviceManager.currentSessionManager()
sessionManager?.enableCallingServicesMode()

Configure the AVAudioSession in the CXStartCallAction or CXAnswerCallAction CXProvider callbacks. Use video chat mode for video calls, or voice chat for audio-only calls.

sessionManager?.preconfigureAudioSessionForCall(withMode: .videoChat)
sessionManager?.preconfigureAudioSessionForCall(withMode: .voiceChat)

Notify to the session manager about audio session activations and deactivations.

func provider(_ provider: CXProvider, didActivate audioSession: AVAudioSession) {
   sessionManager?.audioSessionDidActivate(audioSession)
}
func provider(_ provider: CXProvider, didDeactivate audioSession: AVAudioSession) {
   sessionManager?.audioSessionDidDeactivate(audioSession)
}

Check the CallKit developer documentation for additional information.

iOS 14 networking changes affecting relayed sessions

With iOS 14, Apple introduces local network privacy (see this video).

Beginning in iOS 14, the operating system will prompt the user for permission when an application attempts to subscribe to clients on the same local network in a relayed session. The default text in the notification says that the app "would like to find and connect to devices on your local network."

In a relayed session, the Vonage Video API uses the local network to discover and connect to video participants on your local network when possible. If clients cannot connect on the local network, an application will use the OpenTok TURN server to relay audio-video streams.

If the user does reject the permission, the attempt to subscribe can fail if the client cannot connect to the OpenTok TURN server. In this case, after the permission is rejected, any future attempts to subscribe to clients on the same network will also fail unless the user changes the permission in Settings. Unfortunately, iOS does not provide an API for an application to determine if the user has accepted or rejected this permission.

It is important to note that this does not apply to video sessions that use the Media Router, as media is sent over the internet rather than the local network.

If your application uses a relayed session, we encourage you to add a descriptive custom usage string to inform the user why the application needs this permission:

In Xcode, open your app's info.plist file.
In the info.plist editor, right-click the left-hand column and select Add Row (or click +) to add a setting for Privacy - Local Network Usage Description.
Edit the value for this string to describe how your app uses this permission. For example, add "This app uses the local network to discover and connect to video participants on the same network when possible."

The prompt to the user will include this description.

For applications which cannot use routed sessions and do not wish the user to be prompted for local network access, you can use any of the options in the following sections.

Skip local network checks to establish media connectivity

You can set the OTSessionICEConfig.filterOutLanCandidates property to force the application to not use the local network to establish connectivity, as in the following code.

let settings = OTSessionSettings()
let myICEServerConfiguration = OTSessionICEConfig()
myICEServerConfiguration.filterOutLanCandidates = true
settings.iceConfig = myICEServerConfiguration
let session = OTSession(applicationId: applicationId, sessionId: sessionId, delegate: self,
                        settings: settings)

OTSessionSettings *settings = [[OTSessionSettings alloc] init];
OTSessionICEConfig *myICEServerConfiguration = [[OTSessionICEConfig alloc] init];
myICEServerConfiguration.filterOutLanCandidates = YES;
settings.iceConfig = myICEServerConfiguration;
session = [[OTSession alloc] initWithApiKey:kApplicationId
                                   sessionId:kSessionId
                                    delegate:self settings:settings];

Note: The OTSessionICEConfig.filterOutLanCandidates property is available in the Vonage Video iOS SDK version 2.30.0 and later.

Use TURN servers

You can set the OTSessionICEConfig.transportPolicy to force the application to use TURN servers to establish connectivity, as in the following code.

let settings = OTSessionSettings()
let myICEServerConfiguration = OTSessionICEConfig()
myICEServerConfiguration.transportPolicy = .relay
settings.iceConfig = myICEServerConfiguration
let session = OTSession(applicationId: applicationId, sessionId: sessionId, delegate: self,
                        settings: settings)

OTSessionSettings *settings = [[OTSessionSettings alloc] init];
OTSessionICEConfig *myICEServerConfiguration = [[OTSessionICEConfig alloc] init];
myICEServerConfiguration.transportPolicy = OTSessionICETransportRelay;
settings.iceConfig = myICEServerConfiguration;
session = [[OTSession alloc] initWithApiKey:kApplicationId
                                   sessionId:kSessionId
                                    delegate:self settings:settings];

System requirements

The Vonage iOS SDK is supported in iOS 15 or higher. Check the list of supported devices for iOS 15 here

The Vonage iOS SDK is supported on Wi-Fi, 4G/LTE, and 5G connections.

Sample Apps

For samples visit our Swift sample app repo or Objective-C sample app repo on GitHub.

Documentation

You can find detailed documentation of each iOS method in the reference guide.

More information

For a list of new features and known issues, see the release notes.

Running in background state

See Background state management.