Getting started with the OpenTok iOS SDK

The OpenTok iOS SDK lets you use OpenTok video sessions in apps you build for iPad, iPhone, and iPod touch devices. This means you can use OpenTok video sessions that connect iOS users with each other and with web clients.

The OpenTok iOS SDK uses the same platform architecture and concepts that are used in the OpenTok JavaScript library and the OpenTok ActionScript library. However, you code iOS apps in Objective-C.

This article will explain the most basic parts of the OpenTok iOS SDK. It will also show how the functionality and concepts used in the OpenTok iOS SDK are shared in the OpenTok JavaScript and ActionScript library.

Note: iOS developers do not need to know anything about the OpenTok JavaScript or ActionScript libraries. Similarly, a JavaScript developer does not need to know anything about the OpenTok ActionScript libary or the OpenTok iOS SDK. However, this article shows how similar functionality is defined in each of these client-side libraries.

Setting up your development environment and running the Hello World app

In order to use the iOS SDK, get the latest version of the OpenTok iOS SDK from https://github.com/opentok/opentok-ios-sdk. The OpenTok iOS SDK includes the OpenTok.framework file, which you include in your application. This SDK provides an Objective-C API for connecting to OpenTok sessions, publishing streams, subscribing to streams, and more. Follow the remaining steps on setting up your development environment in Using the OpenTok iOS SDK.

Once you’ve got everything set up, open the OTHelloWorld.xcodeproj file (in the Hello World sample) in XCode. This XCode project connects to the same OpenTok session as used by the Hello World sample applications for the OpenTok JavaScript and OpenTok ActionScript libraries. Follow the instructions for running the application. In addition to the instructions for testing the application, the Hello World documentation provides a description of the Objective-C code in the app.

Sessions, connections, streams, publishers, and subscribers

For an overview of the OpenTok architecture and concepts, see OpenTok API Architecture. You use the OpenTok iOS SDK to connect to an OpenTok session, publish an audio-video stream and subscribe to other clients audio-video streams. As in the other OpenTok client-side libraries (for JavaScript and ActionScript), the OpenTok iOS SDK has classes that represent sessions, connections, streams, publishers, and subscribers: OTSession, OTConnection, OTStream, OTPublisher, and OTSubscriber. Those familiar with the OpenTok JavaScript or ActionScript API will note that these classes define many of the same methods as found in the other client-side libraries. (The naming is different, due to Objective-C conventions and syntax.)

Connecting to a session

To connect to a session, allocate an OTSession object and send the [OTSession initWithSessionId: delegate:] message and then call the [OTSession connect] message:

session = [OTSession alloc];
[session initWithSessionId:_mySessionId delegate:self];
[session connectWithApiKey:kApiKey token:kToken];

Note to JavaScript developers: This Objective-C code corresponds to the TB.init() and Session.connect() methods in the OpenTok JavaScript libary. Objective-C syntax is, as you have noticed, a bit different. The “A really quick overview of some of Objective-C” at the end of this article attempts to explain some of this.

When the session connects, the [OTSessionDelegate sessionDidConnect:] message is sent. (This corresponds to the sessionConnected event in the ActionScript and JavaScript libraries.)

Detecting and subscribing to a streams in a session

The streams property of the OTSession object maintains a dictionary of OTStream objects. When a stream is added to the session, the [OTSessionDelegate session: didReceiveStream:] message is sent. When a stream leaves a session, the [OTSessionDelegate session: didDropStream:] message is sent. These delegate messages correspond to streamCreated to streamDestroyed events in the OpenTok JavaScript and ActionScript libraries.

To subscribe to a stream, initialize an OTSubscriber object by sending the [OTSubscriber initWithStream:delegate:] message:

OTSubscriber* subscriber = [OTSubscriber alloc];
[subscriber initWithStream:stream delegate:self];

This is similar to the Session.subscribe() method in the OpenTok ActionScript and JavaScript libraries.

When the subscriber starts streaming data, the [OTSubscriberDelegate subscriberDidConnectToStream:] message is sent. In the method that handles this message, you can add the subscriber’s view to a superview:

[subscriber.view setFrame:CGRectMake(0, 0, 320, 240)];
[self.view addSubview:subscriber.view];

Publishing a stream

To publish your iOS device’s audio-video stream to an OpenTok session, first initialize an OTPublisher object. Then send the [OTSession publish:] method:

OTPublisher* publisher = [OTPublisher alloc];
[publisher initWithDelegate:self];
[session publish:publisher];

This corresponds to the Session.publish() method in the OpenTok ActionScript and JavaScript libraries.

Add the publisher’s view to a superview:

[_publisher.view setFrame:CGRectMake(0, 0, 320, 240)];
[self.view addSubview:_publisher.view];

As your video starts streaming, the [OTSessionDelegate session: didReceiveStream:] message is sent on other iOS clients. JavaScript and ActionScript clients will recieve the streamCreated event.

A really quick overview of some of Objective-C

This is not meant to be a tutorial on learning Objective-C and iOS programming. But I hope to make some of the Objective-C code mentioned in this article clearer to developers familiar with the OpenTok client-side libraries for JavaScript and ActionScript.

Objective-C adds object-oriented capabilities to C. Objective-C apps are arranged in classes (which define objects). Header (.h) files define the methods and properties exposed by a class. Implementation (.m) files contain the working code. You can view and edit these files in the XCode project navigator. In the OTHelloWorld app, the ViewController class is the main class that contains all of the code that uses the OpenTok iOS SDK.

Note that in Objective-C parlance, you do not call methods of an object. You send a message to an object. (For more information, see this thread at stackoverflow.com.) And the syntax is different than how you call methods in JavaScript or ActionScript (or Java, for that matter). You use bracket, not dot notation, to send a message (which is like calling a method). For example, the following sends the foo message to the obj object:

[obj foo];

In JavaScript, this would be written more like obj.foo().

In Objective-C, you must allocate memory for an object. (This is done automatically in JavaScript and ActionScript.) The sample code above includes statements like the following:

OTPublisher* publisher = [OTPublisher alloc];

The following code shows how to send a message with multiple arguments to an object:

[_session initWithSessionId:kSessionId delegate:self]

This message has two arguments: initWithSessionId and delegate. It’s like a JavaScript method that takes two parameters. The first is a session ID (a string, just like in the JavaScript library), defined by the kSessionId property. The second is a delegate.

A delegate object is an object that handles certain messages for another object. This is how the code handles events dispatched by objects defined by the OpenTok iOS SDK. Rather than using addEventListener() to register methods, as you would using the OpenTok JavaScript library, you assign delegate objects that will receive the delegate messages. (You can think of these messages as callback functions.)

In the case of the OTHelloWorld sample app, here’s a delegate method that handles the event that occurs when the session (the OTSession object) connects:

- (void)sessionDidConnect:(OTSession*)session
{
    // Add code for what happens on this event here.
}

The code (void) says that the method does not return a value. The code (OTSession*) defines the type of object that is passed in.