The OpenTokHello Sample App
The OpenTokHello sample app is a basic sample app that shows the most basic features of the OpenTok iOS SDK.
Important: Be sure to use git clone --recursive [URL]
to grab the required OpenTok iOS SDK submodule!
Once the app connects to the OpenTok session, it publishes an audio-video stream, which is displayed onscreen. Then, the same audio-video stream shows up as a subscribed stream (along with any other streams currently in the session).
Before you test the sample app, be sure to read Using the OpenTok iOS SDK.
Testing the sample app
-
Open OpenTokHelloWorld.xcodeproj in XCode.
-
Connect your iOS device to a USB port on your Mac. Make sure that your device is provisioned and connected to the internet. For more information, see the section on "Setting up your development environment" at this page at the Apple iOS Dev Center.
Note: the OpenTok iOS SDK does not support publishing streams in the XCode iOS Simulator. To test OpenTok apps on an iOS device, you will need to register as an Apple iOS developer at http://developer.apple.com/programs/register/.
-
Configure the project to use your API Key, your own Session, and a Token to access it. If you don't have an API Key sign up for a Developer Account. Then to generate the Session ID and Token, use the Project Tools on the Project Details page.
Open
ViewController.h
and modifykApiKey
,kSessionId
, andkToken
with your own API Key, Session ID, and Token, respectively.Edit
browser_demo.html
and modify the variablesapiKey
,sessionId
, andtoken
with your own API Key, Session ID, and Token, respectively. -
Make sure your attached iOS device is selected in the Scheme chooser. Run the App (press the play button).
The app should start on your connected device. Once the app connects to the OpenTok session, it publishes an audio-video stream, which is displayed onscreen. Then, the same audio-video stream shows up as a subscribed stream (along with any other streams currently in the session).
-
Close the app. Now set up the app to subscribe to audio-video streams other than your own:
-
Near the top of the
ViewController.m
file, change thesubscribeToSelf
property to be set toNO
-
Run the app on your iOS device again.
-
In a browser on your Mac, load the
browser_demo.html
file, included with the sample app, to add more streams to the session. -
In the web page, click the Connect and Publish buttons.
Note: If the web page asks you to set the Flash Player Settings, or if you do not see a display of your camera in the page, see the instructions in Flash Player Settings for local testing.
-
Understanding the code
The ViewController.m
file contains the main implementation code that includes use of the OpenTok iOS API.
Initializing an OTSession object and connecting to an OpenTok session
When the view initially loads, the app allocates an OTSession object and sends it the
[OTSession initWithSessionId:andDelegate:]
message:
- (void)viewDidLoad
{
[super viewDidLoad];
_session = [[OTSession alloc] initWithSessionId:kSessionId
andDelegate:self];
[self doConnect];
}
The kSessionId
constant is the session ID string for the OpenTok session your app connects to. This can be generated from
the Developer Dashboard or from a
server-side library.
The doConnect
method sends the [OTSession connectWithApiKey:token:] to the the _session
object:
- (void)doConnect
{
[_session connectWithApiKey:kApiKey token:kToken];
}
The kToken
constant is the token constant for the client connecting to the session. See Connection Token Creation for details.
When the app connects to the OpenTok session, the OTSessionDelegate (which is the ViewController instance) is sent the
sessionDidConnect:
message:
- (void)sessionDidConnect:(OTSession*)session
{
NSLog(@"sessionDidConnect (%@)", session.sessionId);
[self doPublish];
}
Publishing an audio-video stream to a session
The doPublish
method allocates and initializes an OTPublisher object, and then sends the publish:
message to
the _session
object:
- (void)doPublish
{
_publisher = [[OTPublisher alloc] initWithDelegate:self];
[_publisher setName:[[UIDevice currentDevice] name]];
[_session publish:_publisher];
[self.view addSubview:_publisher.view];
[_publisher.view setFrame:CGRectMake(0, 0, widgetWidth, widgetHeight)];
}
The name of a stream is an optional string that appears at the bottom of the stream's view when the user taps the stream
(or clicks it in a browser). You set the name for the stream by setting the name
property of the OTPublisher object
before you pass it to the session with the publish:
message.
The view of the OTPublisher object is added as a subview of the ViewController's view.
Subscribing to streams
When a stream is added to a session, the OTSessionDelegate is sent the session:didReceiveStream:
message. It then
allocates and initializes an OTSubscriber object for the stream.
- (void)session:(OTSession*)mySession didReceiveStream:(OTStream*)stream
{
NSLog(@"session didReceiveStream (%@)", stream.streamId);
if ( ( subscribeToSelf && [stream.connection.connectionId isEqualToString: _session.connection.connectionId]) ||
(!subscribeToSelf && ![stream.connection.connectionId isEqualToString: _session.connection.connectionId]) ) {
if (!_subscriber) {
_subscriber = [[OTSubscriber alloc] initWithStream:stream delegate:self];
}
}
}
This app subscribes to one stream, at most. It either subscribes to the stream you publish, or it subscribes to one
of the other streams in the session (if there is one), based on the subscribeToSelf
property, which is set at the
top of the file.
The Connection ID for the stream you publish with match the Connection ID for your Session. (Note: in a real application, a client would not normally subscribe to its own published stream. However, for this test app, it is convenient for the client to subscribe to its own stream.)
If the session does not yet have the _subscriber
property set to an OTSubscriber object, it does so in this method.
The OTSubscriberDelegate is sent the subscriberDidConnectToStream
message when the subscriber connects to the
stream. At this point, the code adds the OTSubscriber's view to as a subview of the ViewController:
- (void)subscriberDidConnectToStream:(OTSubscriber*)subscriber
{
NSLog(@"subscriberDidConnectToStream (%@)", subscriber.stream.connection.connectionId);
[subscriber.view setFrame:CGRectMake(widgetWidth * subscriberCount++, widgetHeight, widgetWidth, widgetHeight)];
[self.view addSubview:subscriber.view];
}
The OpenTok iOS SDK supports a limited number of simultaneous audio-video streams in an app:
- On iPad 2 / 3 / 4, the limit is four streams. An app can have up to four simultaneous subscribers, or one publisher and up to three subscribers.
- On all other supported iOS devices, the limit is two streams. An app can have up to two subscribers, or one publisher and one subscriber.
Removing dropped streams
As streams leave the session (when clients disconnect or stop publishing), the OTSessionDelegate is sent the
session:didDropStream:
message.
Subscriber objects are automatically removed from their superview when their stream is dropped.
The code checks to see if you are subscribing to streams other than your own. If so, it checks to see if the
dropped stream matches the subscriber's stream. It does this by comparing the streamId
property of the dropped
OTStream object with the stream.streamId
property of the OTSubscriber:
- (void)session:(OTSession*)session didDropStream:(OTStream*)stream
{
NSLog(@"session didDropStream (%@)", stream.streamId);
if ( !subscribeToSelf
&& _subscriber
&& [_subscriber.stream.streamId isEqualToString: stream.streamId] ) {
_subscriber = nil;
[self updateSubscriber];
}
}
The updateSubscriber
method subscribes to another stream in the session (other than the one you publish), if there is one. The
OTSession.streams
property is a dictionary of all streams in a session:
- (void)updateSubscriber
{
for (NSString* streamId in _session.streams) {
OTStream* stream = [_session.streams valueForKey:streamId];
if (stream.connection.connectionId != _session.connection.connectionId) {
_subscriber = [[OTSubscriber alloc] initWithStream:stream delegate:self];
break;
}
}
}
Knowing when you have disconnected from the session
Finally, when the app disconnects from the session, the OTSubscriberDelegate is sent the sessionDidDisconnect:
message:
- (void)sessionDidDisconnect:(OTSession*)session
{
NSString* alertMessage = [NSString stringWithFormat:@"Session disconnected: (%@)", session.sessionId];
NSLog(@"sessionDidDisconnect (%@)", alertMessage);
}
If an app cannot connect to the session (perhaps because of no network connection), the OTSubscriberDelegate is sent
the session:didFailWithError:
message:
- (void)session:(OTSession*)session didFailWithError:(OTError*)error
{
NSLog(@"sessionDidFail");
[self showAlert:[NSString stringWithFormat:@"There was an error connecting to session %@", session.sessionId]];
}
Next steps
The OpenTokBasic sample app uses more features of the OpenTok iOS SDK than the OpenTokHello app does.
For details on the full OpenTok iOS API, see the reference documentation.