Player SDK for tvOS

Introduction

Ustream Player SDK for tvOS provides an API to play all kinds of Ustream content on Apple Tv. Using this native SDK gives you full control over the Player, including a customizable native user interface, callbacks on status changes, and many more. (Note: if you need none of the above, you may use the HTML-based Player API instead)

This document describes the basic steps to make an app using the Player SDK for tvOS.

Supported tvOS versions

Ustream Player SDK for tvOS requires Xcode 7.1, targeting tvOS 9.0 or above.

Contents of the Package

  • TvOSPlayerSDK.framework - the framework itself, containing a flat binary including architectures: x86_64 arm64
  • tvOSPlayerSDKSample - a sample application using the Ustream Player SDK for tvOS

Integration

Step 1: Adding the framework to your project.

  • Unzip the package and copy the Framework directory into your project’s source directory.
  • Add the framework to your project from Xcode.
  • Make sure that TvOSPlayerSDK.framework is included into Target Settings/Build Phases/Link Binary With Libraries
  • Make sure that Target Settings/Build Settings/Framework Search Paths contains the framework’s parent directory

Step 2: Embed the framework

  • Add a new Copy Files build phase to build phases
  • Set destination to Frameworks
  • Add TvOSPlayerSDK.framework to to list of copied files

Step 3: Configuring the player with your API-key

Before you can create and use an instance of the player you have to configure the lib with your Ustream API key:

			
[USUstreamPlayer configureWithApiKey:];
			
		

Step 4: Creating a player and adding it to your view hierarchy

USUstreamPlayer can be instantiated in the usual way using alloc+init or new.
Sample:

			
self.ustreamPlayer = [[USUstreamPlayer alloc] init];
self.ustreamPlayer.delegate = self;
self.ustreamPlayer.view.frame = self.view.bounds;
self.ustreamPlayer.view.autoresizingMask = UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight;
[self.view addSubview:self.ustreamPlayer.view];
			
		

Step 5: Start playing content

At this point your player is correctly configured and ready to play Ustream-provided media, USUstreamPlayer is capable to play three different kinds of media:

  • live streams using the -[USUstreamPlayer playChannel:] API call.
  • recorded videos using the -[USUstreamPlayer playRecorded:] API call.
  • highlights using the -[USUstreamPlayer playHighlight:] API call.

Sample:

			
[self.ustreamPlayer playChannel:];
			
		

Step 6: Handling callbacks

USUstreamPlayer reports its state changes and requires user interaction in case of some locks using the USPlayerDelegate protocol.
In order to catch these callbacks you have to set a handler conforming to protocol USPlayerDelegate as a delegate of your player instance.

Sample:

			
self.ustreamPlayer.delegate = self;
			
		

List of Interactive Callbacks

- (void)playerRequiresPassword:(USUstreamPlayer *)player - When the player sends this callback it waits for a password for the locked content. You can provide the password using continueWithPassword:(NSString *)password. If you provide the password the player validates it and starts playing the content if the password is valid otherwise it calls back again with playerRequiresPassword.

- (void)playerRequiresAgeConfirmation:(USUstreamPlayer *)player ageRequired:(NSUInteger)age -When this callback is sent you must ask the user to confirm he is older than the age required. If the user confirms it you can continue the playback with continueWithAgeConfirmed.

- (void)playerRequiresBirthdate:(USUstreamPlayer *)player - When this callback is sent you must ask the user to give his/her birthdate in order to check if he/she is old enough to watch the content. You can continue the playback with continueWithBirthdate:(NSDate *)birthdate;

Note: Beside these locks there are a number of other, non-interactive locks listed in the appendix. In those cases there is no way to continue the playback.

- (void)playerStateDidChange:(USUstreamPlayer *)player - This callback is called whenever the player’s state is changed and allows you to act on it. The possible states are listed in the USPlayerState enum.

Customizing the player UI

By default USUstreamPlayer comes with a full-featured user interface, including a control bar, loading and error views. This is used if the player’s playerControlStyle property is set to USPlayerControlStyleDefault.

You can change this behaviour by setting the playerControlStyle property of the player. By setting it to USPlayerControlStyleNone you can instruct the player to present media without any decoration views.

In case you don’t want to handle all the player states and error cases manually, you can reconfigure the control bars as well, by setting their content using the USUstreamPlayer (USToolbar) category. In order to do so, set the playerControlStyle property to USPlayerControlStyleToolbar.

You can set any of the player toolbar’s contents using the -[USToolbar setToolbarItems:animated:] API. The standard toolbar items are accessible in the USUstreamPlayer (USToolbar) category, and you can create your own items as well by subclassing USToolbarItem.

Localization

Ustream provides localizations for all strings used in the Ustream Player SDK for tvOS in the following languages:

  • English
  • Spanish
  • Japanese
  • Korean

If you want to provide more languages and/or redefine the texts include the keys listed in appendix into your app’s localization files. If you don’t redefine these keys the SDK will fall back to the localizations included in the SDK’s resource bundle.

Appendices

Appendix 1 - Ustream Media Locks:

Lock name Applicable Note
Password lock live, recorded, highlight Broadcaster can manage this lock here: http://www.ustream.tv/manage-show/advanced/cid
Age lock live, recorded, highlight This lock is not available for end users to control. It’s part of special deals conducted by Ustream sales and administered internally.
Birthdate lock live, recorded, highlight This lock is not available for end users to control. It’s part of special deals conducted by Ustream sales and administered internally.
Geo lock live, recorded, highlight This lock is not available for end users to control. It’s part of special deals conducted by Ustream sales and administered internally.
GeoLimit lock live, recorded, highlight This lock is not available for end users to control. It’s part of special deals conducted by Ustream sales and administered internally.
Hash lock live Broadcaster can manage this lock here: http://www.ustream.tv/manage-show/webinar/cid
IP lock live, recorded, highlight This lock is not available for end users to control. It’s part of special deals conducted by Ustream sales and administered internally.
Referrer lock live, recorded, highlight Broadcaster can manage this lock here: http://www.ustream.tv/manage-show/embed/cid

Appendix 2 - Ustream Player SDK for tvOS Localization Keys:

Key English value
USPlayer.preroll.premium Enjoy ad-free experience with Premium Membership!
USPlayer.preroll.resuming "Resuming in %d seconds"
USPlayer.preroll.status.loading Loading...
USPlayer.content.status.offline This channel is off-air.
USPlayer.content.status.realizing Initializing...
USPlayer.content.status.unrealized Loading failed, please try again.
USPlayer.content.lock.ageLock++ This content is age-restricted.
USPlayer.content.lock.birthdateLock This content is age-restricted. Please provide your birthdate.
USPlayer.content.lock.geoLimitLock Too many viewers in your area.
USPlayer.content.lock.geoLock This content is not available in your area.
USPlayer.content.lock.hashLock This content is not supported in the mobile apps. Please use a browser for watching.
USPlayer.content.lock.IPLock This content is not available in your network.
USPlayer.content.lock.passwordLock This content is password-protected.
USPlayer.content.lock.refererLock Viewer limit exceeded.
USPlayer.content.lock.unknownLock This content is not supported.
USPlayer.content.error.update Sorry, something went wrong. Please try again.
USPlayer.content.error.connect Connection error. Please try again.
USPlayer.content.error.unsuported Unsupported content.
USPlayer.content.error.deleted This video has been removed by the owner.
USPlayer.content.error.inexistent This content is inaccessible. Try again later.
USPlayer.content.error.unknown Sorry, something went wrong. Please try again.
USPlayer.content.error.authentication Invalid password.
USPlayer.content.error.timeout Loading timeout, please try again.
USPlayer.player.external.title AirPlay
USPlayer.player.external.message This video is playing on "Apple TV".
USPlayer.player.audioOnly Playing audio only...
USPlayer.player.status.buffering Buffering...
USPlayer.control.viewerCount %d viewers
USPlayer.player.started.justNow Started just now
USPlayer.player.started.years Started years ago
USPlayer.player.started.months Started months ago
USPlayer.player.started.weeks Started weeks ago
USPlayer.player.started.days Started days ago
USPlayer.player.started.hours Started %dh %dm ago
USPlayer.player.started.minutes Started %dm ago
USPlayer.player.status.finished finished
USPlayer.content.error.age Age unconfirmed or too young user