Twilio Client iOS 1.x SDK Background Best Practices

Here are Twilio's suggested best practices for developers who wish to configure their applications or implementations so that the Twilio Client iOS SDK works gracefully when the Client application is in the background.

Application configuration

In the Xcode iOS application, go to Capabilities in the project settings and enable “Voice over IP” and “Audio, AirPlay and Picture in Picture”.

The setKeepAliveTimeout:handler: API

If your application is running on an iOS version earlier than 8.0, the TwilioClient iOS SDK uses UIApplication to register itself so the application can be woken up every 600 seconds to ensure the connection between the mobile client and the Twilio service is maintained. Since iOS only allows one instance to be registered with this API, please let the SDK do the heavy lifting here and do not attempt to manually add this into your application logic.

For iOS 8.0 and later, please refer to VoIP Best Practices by Apple. By sending a push notification to the mobile client whenever you want it to receive an incoming connection, the VoIP-enabled application is provided enough time to ensure the connection between the VoIP service and the mobile application is active so that the application can receive incoming invites, or to establish a connection if one is not active.

If your application is running on iOS 8.0 or later, Apple suggests VoIP apps register for registerForRemoteNotifications notifications instead of relying on the setkeepAliveTimeout:handler API to check in with the VoIP service. Though the setkeepAliveTimeout:handler API is deprecated in iOS 9.0, using the API won’t cause any linking or runtime errors; however, this API will eventually go away.

Add local notification to the app

While your VoIP application may not always be active in the foreground, you still want to be able to answer incoming call, but how is this accomplished? In the device:didReceiveIncomingConnection: delegate method, create a UILocalNotification and fire it right away:

- (void)device:(TCDevice *) didReceiveIncomingConnections:(TCConnection *)connection {
UILocalNotification *notification = [[UILocalNotification alloc] init];
notification.alertBody = @"Incoming Call";
notification.fireDate = [NSDate date];
NSArray *oldNotifications = [[UIApplication sharedApplication] scheduledLocalNotifications];
if ([oldNotifications count] > 0) {
[[UIApplication sharedApplication] cancelAllLocalNotifications];

[[UIApplication sharedApplication] scheduleLocalNotification:notification];

What if the connection expired when the app is in the background?

Apple's best practices for VoIP applications suggests to use push notification (PushKit) for iOS 8.0 and later, which Twilio Client 1.x infrastructure and SDK don’t support. With this in mind, the best way for the client apps to stay connected is to trigger an UILocalNotification when the capability token has expired in the background so that end users can revisit the app and new capability token can be generated and re-register to the service.

To use PushKit in your application use the Programmable Voice SDK 2.0 or later.

How does the Twilio Client SDK works to keep the connection, even when the app is in the background?

To ensure that the applications can receive incoming calls even when the application is in the background, mobile clients rely on the Twilio Client SDK to maintain the connection between the Twilio service and the application.

In addition, the Twilio Client SDK registers for a handler using the setKeepAliveTimeout:handler: API of the UIApplication class. Whenever the SDK detects that the application is going to the background, it uses this API with a 600-second timeout interval so that iOS will wake up the application from suspended state every 10 minutes. The SDK will then use the wakeup time to refresh the connection as long as the capability token has not yet expired.

Is there a way for the application to get the mobile client back to “connected” if it becomes disconnected?

Mobile clients become unreachable upon capability token expiration, or due to certain undesirable network conditions, and will therefore be unable to receive incoming invites. The SDK notifies the applications via the device:didStopListeningForIncomingConnections: delegate method whenever it stops listening for incoming connections. Here is an example that shows how to resume the connection in the delegate callback:

- (void)device:(TCDevice *) didStopListeningForIncomingConnections:(NSError *)error {
if ([self _isCapabilityTokenValid] && self.device) {
* if the TCDevice instance is valid and so is the capability token, call
* the `listen` method
[self.device listen];
else {
* generate a new capability token and use it to setup/update the TCDevice
[self _setupTwilioClient];

If your application is push-notification-enabled, you can send a push notification to the callee when the caller fails to reach the callee, e.g., the capability token of the callee has expired or the network condition of the callee may be poor.

Have more questions? Submit a request
Powered by Zendesk