Getting Started with the Video Cloud App SDK for iOS

This document describes the Video Cloud App SDK for iOS, which enables you to develop your own native application to deliver your Video Cloud videos to the iPhone, iPad, and other Apple iOS platforms. In addition to this "getting started" article, check out these other documents:

Video Cloud App SDK for iOS. Links to the zip files that include the latest versions of the SDK classes, reference docs, and sample code for the OnePlanet iPhone native app.
Video Cloud App SDK for iOS Reference. An on-line reference for the Video Cloud App SDK for iOS.
Best Practices for Developing Video Cloud Apps for iOS. Tips, tricks, and important points to remember as you develop your Video Cloud iOS application.
Known Issues for the Video Cloud App SDK for iOS.

The Video Cloud App SDK for iOS is a set of Cocoa/Objective-C Libraries for employing the Video Cloud Media API and for playing videos in a custom Video Cloud movie player on Apple iOS devices like the iPhone, iPad, and iPod Touch. The Media API provides a Cocoa/Objective-C interface for the Video Cloud video and playlist APIs. The player component adds support for email and Twitter sharing, and related and popular video overlays to the standard iOS video player.

With the expansion of the iTunes App Store, as well as the popularity of iPhone and iPad devices, the demand for mobile media continues to grow. Using this SDK to create a native iOS application will help you create a unique experience for viewers. You can easily access and retrieve your video content and metadata using the SDK so you can tailor your app for viewers on the go and keep your brand visible and close to your audience at all times.

If you are considering building an iOS application, it's never too early to start preparing your video content for mobile delivery. Read more about encoding video for mobile delivery. You may also want to consider building a mobile web application; read more about how Brightcove can help.

The Video Cloud App SDK for iOS requires that you have Apple iOS SDK version 3.1 or higher.

OnePlanet Sample Application

We used the 2.1 version of the Video Cloud App SDK for iOS to develop a sample native iPhone and iPad app named OnePlanet. Read about how we developed OnePlanet and download the source code for the iPhone and iPad versions of the app.

You can also get this free app for iPhone or iPad in the iTunes App Store.

Installing the Video Cloud App SDK for iOS in Xcode

To install the Video Cloud App SDK for iOS:

Open Xcode and Create or Open an Xcode project.
Select the Project's Target and then Get Info (click the target in the Xcode pane, then command-I or File > Get Info).
Choose the Build tab.
Double-click the Other Linking Flags property in the Linking section of the Settings list and add the following flag:
```
         -all_load -ObjC
```
Choose the General tab and under the Linked Library section, click the plus button.
A dialog will slide down. Click the Add Other... button.
Now select the libBrightcoveMediaAPI.a file, which is distributed in the Video Cloud Media API zip in the lib folder.
Repeat steps 5 and 6 for the libBCiPhoneKit.a file, which is distributed in the Video Cloud iPhone Kit zip in the lib folder.
Close target settings.
Open Project Settings (Project > Edit Project Settings).
In the Search Paths section, in the Header Search Paths entry, add the directory in which you put the Video Cloud Media API zip on your computer followed by /lib. For example, if you stored the bc-media-api-1.2.1 at /Developer/Brightcove on your computer, then you would enter /Developer/Brightcove/bc-media-api-1.2.1/lib . IMPORTANT: Ensure that the "recursive" checkbox is selected.
In the Search Paths section, in the Header Search Paths entry, add the directory in which you put the Video Cloud iPhone Kit on your computer followed by /lib. For example, if you stored the bc-ipad-iphone-kit-1.1.0 at /Developer/Brightcove on your computer, then you would enter /Developer/Brightcove/bc-ipad-iphone-kit-1.1.0/lib . IMPORTANT: Ensure that the "recursive" checkbox is selected.
Close Project Settings.
Add the required Apple frameworks to your project. In the 'Frameworks' section of your Project in Xcode, ensure that all of these frameworks are present:

Foundation.framework
CoreGraphics.framework
UIKit.framework
MediaPlayer.framework
OpenGLES.framework
QuartzCore.framework.

If any of those frameworks are missing, right-click on the Frameworks group in Xcode, select Add and Existing Frameworks... to open a file browser that will allow you to select and add the frameworks to your project. NOTE: If you want to use only the Video Cloud Media APIs and not the Video Cloud iPhone video player, you do not need to include MediaPlayer.framework, OpenGLES.framework, and QuartzCore.framework.

If you are using the Video Cloud iPhone video player, then you will need to add the Video Cloud image bundle:

Find the directory in which you put the Video Cloud iPhone Kit on your computer. It contains the BCMoviePlayer.bundle file.
Either drag this file into your Xcode project, or right-click the project tree in Xcode, select Add > Existing Files... and select the bundle to add it.

You can style these images yourself by replacing them in the bundle, so long as you retain the same names for your new images.

Media API Usage

The BCMediaAPI class is a facade for all Video Cloud Media API calls. This enables developers to instantiate it once for any needed calls:

    BCMediaAPI *bc = [[BCMediaAPI alloc] initWithReadToken:@"MyApiKey"];

Invocations are handled using Cocoa-style error pointers; thus, the pattern for all invocations is as follows:

Create an NSError object if you desire error info (optional).
Invoke a BC Media API method which will return a BCVideo, BCPlaylist, or BCItemCollection.
Check whether the returned BCObject is nil, and if so examine the NSError (if you used one).
If the returned BCObject was not nil, then access its properties according to your app's needs.

Media API Example Code

// Don't forget to include this line in your source (uncommented):
// #import "BCMediaAPI.h"

 BCMediaAPI *bc = [[BCMediaAPI alloc] initWithReadToken:@"MyApiKey"];

 NSError *err;
 BCVideo *video = [bc findVideoById:1234 error:&err];
 
 if (!video) {
    // if the result is nil, and we sent the optional error argument,
    // then the error will be populated by all underlying errors reported
    // by the Video Cloud server. We can use the following convenience method
    // to dump the NSError's userInfo, where the underlying errors are reported,
    // into an NSString for logging or other purposes:
 
    NSString *errStr = [bc getErrorsAsString:err];
    NSLog(errStr);
 }

Player Component Usage

The BCPlayer class is the public component which allows you to play and stop videos:

    BCPlayer *bcPlayer = [[BCPlayer alloc] init];

You play a video using an instance of the BCVideo class found in the BCMedia API. Although this BCVideo instance is typically retrieved dynamically using the BC Media API, it can also be created programmatically. You may also retrieve a BCVideo instance using the BC Media API and subsequently override properties on the instance by setting them programmatically.

    BCVideo *myVideo = [[self getVideoObject:videoId] retain];
    [bcPlayer play:activeVideo];

If you want to enable sharing, you should also set a playerId on the BCPlayer instance so that email and Twitter URL links can be composed to direct users to your correct web-based Video Cloud player.

If you want to show related videos or popular videos in the player as a coverflow overlay, then add those arrays of BCVideo instances to the player.

Register a BCPlayerDelegate on the BCPlayer which implements the BCPlayerDelegate protocol to receive notice when various events occur in the player:

    bcPlayer.delegate = self;

The delegate callbacks enable access to events including the following:

The main content video is complete
A related video has been selected by the user

BCPlayer Example Code

// Don't forget to include this line in your source (uncommented): 
// #import "BCPlayer.h" 
- (void) playMyMovie { 
    NSString *apiKey = @"keyWithAdditionalURLPrivileges"; 
    bcAPI = [[BCMediaAPI alloc] initWithReadToken:@"MyApiKey"]; 
    double videoId = 25348489001L; 
    bcPlayer = [[BCPlayer alloc] init]; 
    bcPlayer.delegate = self; 
    bcPlayer.playerId = 25309144001L; 
 
    // without this, sharing will not work 
    // Use the BCMediaAPI to create a BCVideo instance: 
    activeVideo = [[self getVideoObject:videoId] retain]; 

    // Set popular and related videos if desired, which can be done either programmatically 
    // by creating BCVideo objects or automatically through the BCMediaAPI: 
    bcPlayer.popularVideos = [self getPopularVideos]; 
    bcPlayer.relatedVideos = [self getRelatedVideos:videoId]; 
 
    // NOTE: If you do not set related or popular videos, the video browsing menu will not appear 
    // NOTE: If you set related videos but not popular videos, or vice versa, then the video 
    // browsing will appear, but the switch to move between popular and related videos will 
    // not appear.
    // All of the following settings are true by default, but you can override them to control
    // which menus appear: 
    bcPlayer.shareMenuEnabled = NO; 
    bcPlayer.moreVideosMenuEnabled = YES; 
    bcPlayer.showRelatedMoviesOnComplete = YES; 

    // By default, related and popular videos are rendered using a coverflow UI, but you can use 
    // a UITableView instead by setting this property to NO. You may wish to do this if you 
    // see performance issues with coverflow on your particular application (this property 
    // value is YES by default) 
    bcPlayer.useCoverflow = YES; 

    // play the video 
    [bcPlayer play:activeVideo]; 
} 

#pragma mark BCPlayerDelegate callback methods 

- (void) playerComplete {
   NSLog(@"Player Is Complete");
}

- (void) selectedRelatedVideo:(BCVideo *) relatedVideo { 

// app has the option of reclaiming control, changing the playerId for sharing, etc. 

    bcPlayer.playerId = 25309144001L; // you might need to change the playerId for a new video for sharing to work
}

If you need help or have a question, please visit our forums. You can also follow the Video Cloud App SDK for iOS on Twitter: http://twitter.com/bciphonesdk or register for updates and announcements by e-mail about our mobile SDKs.

Video Cloud

App Cloud

Resources