iOS Second Screen Client Quickstart

The Red5 Pro Second Screen iOS SDK provides the ability to add Second Screen experiences to your Native Applications on iOS devices.

Download the Red5 Pro iOS Second Screen SDKs Download the latest
Second Screen Native Client SDK for iOS

Included in the Red5 Pro iOS Second Screen SDK is an example project with Xcode support.


Requirements

The Red5 Pro iOS Second Screen SDK supports iOS 6.x and above.


Basic Setup

Once you have downloaded Xcode and the Red5 Pro iOS Second Screen SDK, open Xcode and create a new project or open an existing project you want to add Second Screen to. To add the Red5 Pro Second Screen libraries to your project:

Adding the Framework and Bundle

Drag SecondScreen.framework and SecondScreen.bundle into your Xcode project. Make sure that they are added to the desired target.

Adding Required Frameworks

Go to your target settings, select the "Build Phase" section and expand the "Link Binary With Libraries" phase. Link against the following frameworks:

AudioToolbox.framework
CFNetwork.framework
CoreGraphics.framework
CoreMotion.framework
CoreText.framework
QuartzCore.framework
Security.framework

Modifying the .plist (optional)

In your *-Info.plist, set UIRequiresPersistentWiFi to YES and add wifi to the listing of Required device capabilities. This is not strictly required, but will the prevent the OS from shutting off the wifi while the application is in use.

Including the header

You can now use the SDK from any of your implementation files by adding the Second Screen SDK header file:

#import <SecondScreen/SecondScreen.h>

Configuration

The second screen client must be configured before it is used. This is most simply done in the the application delegates's application:didFinishLaunchingWithOptions: method. The registry server hostname is required, and other things can be optionally configured.

R5SecondScreenClient* client = [R5SecondScreenClient sharedClient];
[client setRegistryHostname:@"REGISTRY_HOSTNAME_HERE" port:8088];
[client setClientName:[[UIDevice currentDevice] name]];
[client start];

Calling start will cause the client to maintain a connection to the registry server and any connected host. If the second screen client is only used for a small subset of the app, start and stop can be called explicitly when appropriate.


Registering a delegate

One is notified about updates from second screen client by registering a R5SecondScreenDelegate. This is a protocol with optional methods for being notified about when the list of available hosts changes, a host connects, or a host disconnects. Multiple delegates can be registered at the same time.

A delegate is added like this:

// (if self implements R5SecondScreenDelegate)
[[R5SecondScreenClient sharedClient] addDelegate:self];

A delegate is removed like this:

[[R5SecondScreenClient sharedClient] removeDelegate:self];

Then the delegate will be called for any of the R5SecondScreenDelegate methods that it implements:

-(void) hostListDidChange:(NSArray*)hosts {
    // do something with the array of available R5HostInfo
}

-(void) hostDidConnect:(R5HostSession*)host {
    // ...
}

-(void) hostDidDisconnect {
    // ...
}

Connecting to a Host

Once it is started, the client will begin listening for available hosts. Any R5SecondScreenDelegates will be notified when the list of available hosts changes if they implement hostListDidChange:. Once you have a host that you want to connect to, call the call the requestConnectionFrom: method.

[[R5SecondScreenClient sharedClient] requestConnectionFrom:host];

Binding to a Second Screen View

The R5SecondScreenView is responsible for loading and displaying the controls specified by the host. A second screen view can be created in the interface builder, or programmatically through code.

One can display the progress of loading the controls by setting the view's progressDelegate property to an object that conforms to the R5ProgressDelegate protocol. This will usually be a UIProgressView.

Once connected to a host, one can bind the view to the host session very easily:

[session bindToView:_secondScreenView];

Remote Procedure Calls

Sending RPCs

Once connected to a host, one can also send remote procedure calls to and from the host. To send RPCs to the host, simply call the sendRpc method on the R5HostSession. It takes the name of the method, and an array of any combination of string, numeric, or boolean arguments.

[session sendRpc:@"foo"];
[session sendRpc:@"testing" withParameters:@[@1, @2, @3]];
[session sendRpc:@"enableRobot" withParameters:@[@YES]];
[session sendRpc:@"seenAdjective" withParameters:@[@"spooky"]];

Handling RPCs

One handles RPC calls from the host by specifying an RPC target.

session.rpcTarget = target;

RPCs are resolved to a method call with the same name. Parameters after the first are prefixed with a single :.

-(void) foo {
    // use your imagination
}

-(void) testing:(int)a :(int)b :(float)c {
    // use your imagination
}

-(void) enableRobot:(BOOL)enabled {
    // use your imagination
}

-(void) seenAdjective:(NSString*)adjective {
    // use your imagination
}

Important Note about deploying to iOS 9

It is important to note that since the release of iOS 9, security restrictions have been added for sites loaded using WKWebView and UIWebView — which are used by the Second Screen SDK. You can read more about the restrictions and how to lessen them for your applications form the Apple Developer Documentation.

If you are building an application with Red5 Pro Second Screen and intend support devices with iOS 9, you will need to modify your .plist file appropriately.

Allowing Arbitrary Loads on iOS 9

To modify the .plist file to load Second Screen in your application when targeting iOS 9:

  1. Open the applications .plist file in Xcode
  2. At the top of the file, scroll over Information Property List
  3. Click on the (+) button shown on rollover
  4. In the new property field, enter NSAppTransportSecurity and press the Enter to create the entry
  5. The entry will likely change to the human-readable description of App Transport Security Settings
  6. You will now need to add a subfield for App Transport Security Settings
  7. Rollover the App Transport Security Settings and click on the (+) button
  8. In the new entry field, select Allow Arbitrary Loads
  9. In the Value field for Allow Arbitrary Loads change the value to YES

Allow Arbitrary Loads on iOS 9

This allows any site with the http protocol to be loaded into the Control Scheme for the Device Client. Most likely, you will be deploying the Red5 Pro Server to a specific location and will know where the Control Scheme will be loaded from. In such a case, you can fine-tune this configuration and only allow HTTP requests to be loaded securely from that location.

Please refer to the Apple Developer documentation for further information.


API Documentation

For more in-depth documentation about the structure of the iOS Second Screen Native Client SDK, please visit: iOS Second Screen API Documentation


Native Client Example

We have created and shared an example of an iOS Native Client project that incorporates the Live Streaming and Second Screen SDKS.

Download the iOS Red Pro Native Client Example Download the latest
Native Client Example for iOS