In this tutorial we 'll go over the steps to integrate the WebRTC enabled Restcomm iOS SDK into your Apps to tap into the Restcomm telecom capabilities.

Prerequisites

  • Restcomm Communications Platform

  • Xcode 9.0 with at least iOS SDK 10.0 or higher

1. Restcomm

You first need to install the latest Restcomm Docker image locally (i.e. $ docker pull restcomm/stable to get it from docker hub). For more information please check here. If you aren’t familiar with docker you can have a quick intro here

2. Restcomm iOS SDK

Once you have installed the Restcomm platform you are ready to start taking advantage of Restcomm’s features from your iOS Applications. Notice that the SDK is distributed via CocoaPod 'restcomm-ios-sdk', so you can integrate it with your App in a snap -we 'll discuss about that in a bit at Create a new Xcode iOS App from scratch

Use the existing sample iOS App, 'HelloWorld'

For now let’s try the Hello World Sample App to get acquainted:

  • Grab the latest Restcomm iOS SDK release from GitHub. At the time of this writing it is 1.0.0-beta.5 and the bundle you need to download is restcomm-ios-sdk-1.0.0-beta.5.tar.bz2

  • Extract it:

    $ tar -jxvf restcomm-ios-sdk-1.0.0-beta.5.tar.bz2

To illustrate the SDK, first we’ll be using one of the sample Apps provided in the bundle, called 'Hello World':

  • Hello World installs the SDK dependency via CocoaPods itself, so you need to setup the restcomm-ios-sdk dependency like so (after changing directory to Examples/restcomm-helloworld):

$ pod install
Analyzing dependencies
Fetching podspec for `restcomm-ios-sdk` from `../../`
Downloading dependencies
Installing restcomm-ios-sdk (1.0.0-beta.5)
Installing sofia-sip-library (1.12.11.6)
Installing webrtc-framework (14493.4)
Generating Pods project
Integrating client project
Sending stats
Pod installation complete! There is 1 dependency from the Podfile and 3 total pods installed.
  • Now that dependencies are setup open Hello World sample Xcode workspace from $IOS_SDK/Examples/restcomm-helloworld/restcomm-helloworld.xcworkspace

  • After the Xcode workspace opens, edit file ViewController.mm source file within restcomm-helloworld dir, search for string 'CHANGEME' and perform required changes in the Restcomm instance IP address to reflect your docker instance IP:

    - (void)viewDidLoad
    {
        ....
        self.parameters = [[NSMutableDictionary alloc] initWithObjectsAndKeys:
                           @"bob", RCAorKey,
                           @"1234", RCPasswordKey,
                           nil];
    
        // CHANGEME: set the IP address of your RestComm instance in the URI below (or leave empty for registrar-less access)
        [self.parameters setObject:@"<docker ip address>:5080" forKey:RCRegistrarKey];
    
        // initialize RestComm SDK by setting up an RCDevice
        self.device = [[RCDevice alloc] initWithParams:self.parameters delegate:self];
        ....
    }
    
    - (IBAction)dialPressed:(id)sender
    {
        ...
        // CHANGEME: set the number of the RestComm Application you wish to contact (currently we are using '1235',
        // which is the Hello World RestComm Application). Also set the ip address for your RestComm instance
        [self.parameters setObject:@"+1235" forKey:RCUsername];
    
        // call the other party
        self.connection = [self.device connect:self.parameters delegate:self];
    }
  • Build and run Hello World either on the Xcode simulator or your device.

  • Once the sample App starts up you can press Dial and behind the scenes number '+1235' will be called on the Restcomm instance and you will hear the associated announcement.

  • From then on, you can try even more fun experiments, such as calling a different Restcomm number by changing the whole URI in the code from +1235 to for example +1311 which is the default Restcomm Application for conferencing:

    - (IBAction)dialPressed:(id)sender
    {
        ...
        // CHANGEME: set the number of the RestComm Application you wish to contact (currently we are using '1235',
        // which is the Hello World RestComm Application). Also set the ip address for your RestComm instance
        [self.parameters setObject:@"+1311" forKey:RCUsername];
    
        // call the other party
        self.connection = [self.device connect:self.parameters delegate:self];
        ...
    }

    Now the real fun begins: you can call the same number using the iOS SDK from yet another iOS device or simulator and start a conference between the two!

Create a new Xcode iOS App from scratch

Next, we 'll be going in more detail over the steps it takes to come up with an App similar to HelloWorld starting from a 'Single View' Xcode iOS Application. That way you 'll get a good idea what you need to do to incorporate it in an existing iOS App, or as described below come up with a new App from scratch:

  • Create a single view Application. Xcode > File > New > Project and pick a 'Single View Application':

    Single View Application

  • Pick a project name and a location and press Create.

  • Once the new Xcode project opens, you need to close it and add the dependencies to your project via CocoaPods (CocoaPods updates your project files, hence the need to close it). To do that you need to install CocoaPods if you don’t have them already, check here for more information.

  • Once CocoaPods are installed, you need to go to your Xcode project dir and initialize your Podfile like so:

$ pod init
  • Then you need to edit the newly created Podfile and add the line pod restcomm-ios-sdk like so:

# Uncomment the next line to define a global platform for your project
# platform :ios, '10.0'

target 'your-target' do
  # Pods for your-project
  pod 'restcomm-ios-sdk', '>= 1.0.0-beta.5'

  ...
end
  • Do the actual installation of the dependencies:

$ pod install
  • Once the installation is done you can open the newly created workspace by CocoaPods that combines your project along with the newly installed dependencies using Xcode.

  • In your App main View Controller header, include the SDK, create required objects and also adopt specific SDK protocols so that you can receive events:

    #import <UIKit/UIKit.h>
    #import "RestCommClient.h"
    
    @interface ViewController : UIViewController<RCDeviceDelegate,RCConnectionDelegate>
    @property (nonatomic,retain) RCDevice* device;
    @property (nonatomic,retain) RCConnection* connection;
    // this is not mandatory but let's keep all our parameters in our ViewController in case we need them
    @property NSMutableDictionary * parameters;
    @end
  • Add some bootstrap code in viewDidLoad of your main View Controller. Remember to use the correct IP for your Restcomm docker instance:

    - (void)viewDidLoad {
        [super viewDidLoad];
        // Do any additional setup after loading the view, typically from a nib.
    
        self.parameters = [[NSMutableDictionary alloc] initWithObjectsAndKeys:
                           @"bob", RCAorKey,
                           @"1234", RCPasswordKey,
                           nil];
    
        // CHANGEME: set the IP address of your RestComm instance in the URI below (or leave empty for registrar-less access)
        [self.parameters setObject:@"<docker instance ip>:5080" forKey:RCRegistrarKey];
    
        // initialize RestComm SDK by setting up an RCDevice
        self.device = [[RCDevice alloc] initWithParams:self.parameters delegate:self];
    }
  • Open Main.storyboard from the Project Navigator and add the UI controls: let’s use one button for dialing and one for hang up (don’t worry if the view looks too big -in latest Xcode installations a bigger view is used to accommodate more than one device -but you can see how this will look in your device in the Preview window on the right):

    image

  • Then connect the UI controls to actions in the ViewController code:

    image

  • Add Restcomm iOS SDK calls to the actions you just created to integrate with Restcomm. [RCDevice connect] will make the call and return the established connection (when we press Dial), while [RCConnection disconnect] will disconnect the connection (when we press Hang up). Again, remember to use the correct IP address for the Restcomm instance you are using:

    - (IBAction)dialPressed:(id)sender {
        // CHANGEME: set the number of the RestComm Application you wish to contact (currently we are using '1235',
        // which is the Hello World RestComm Application). Also set the ip address for your RestComm instance
        [self.parameters setObject:@"+1235" forKey:RCUsername];
    
        // do the call
        self.connection = [self.device connect:self.parameters delegate:self];
    }
    
    - (IBAction)hangupPressed:(id)sender {
        // disconnect the established RCConnection
        [self.connection disconnect];
    
        self.connection = nil;
    }

    At this point you will get some warnings again because we haven’t configured Xcode yet, but we’ll do it pretty soon.

  • Rename ViewController.m to ViewController.mm to be able to use C++ code (which some includes of some libs use)

  • Go to Build Settings for your main target, search for 'bitcode' and set 'Enable Bitcode' to No.

  • Implement the needed RCDevice and RCConnection callbacks defined in RCDeviceDelegate and RCConnectionDelegate protocols so that you get back events from the RestCommClient library:

    // ---------- Delegate methods for RC Device
    - (void)device:(RCDevice*)device didStopListeningForIncomingConnections:(NSError*)error
    {
    
    }
    
    - (void)deviceDidStartListeningForIncomingConnections:(RCDevice*)device
    {
    
    }
    
    // received incoming message
    - (void)device:(RCDevice *)device didReceiveIncomingMessage:(NSString *)message
    {
    }
    
    // 'ringing' for incoming connections
    - (void)device:(RCDevice*)device didReceiveIncomingConnection:(RCConnection*)connection
    {
    }
    
    - (void)device:(RCDevice *)device didReceivePresenceUpdate:(RCPresenceEvent *)presenceEvent
    {
    
    }
    
    - (void)deviceDidInitializeSignaling:(RCDevice *)device
    {
    }
    
    // ---------- Delegate methods for RC Connection
    - (void)connection:(RCConnection*)connection didFailWithError:(NSError*)error
    {
    
    }
    
    - (void)connectionDidStartConnecting:(RCConnection*)connection
    {
    
    }
    
    - (void)connectionDidConnect:(RCConnection*)connection
    {
    
    }
    
    - (void)connectionDidDisconnect:(RCConnection*)connection
    {
    }
    
    - (void)device:(RCDevice *)device didReceiveConnectivityUpdate:(RCConnectivityStatus)deviceState
    {
    
    }
  • You are now ready to build and run your project! Press the Play button in Xcode and wait for the App to load. It should look like this:

    iphone-sample-app

  • Now press dial and the SDK will call the configured Restcomm instance and voila, you will hear the announcement! You can press Hang up to terminate the call whenever you like.

That’s it! Give it a try it and share your experience with the rest of the Restcomm community! Here are some additional resources: