Best Practices for Developing Video Cloud Apps for iOS

Product
Video Cloud
Applies to Roles
Developer
Version
Brightcove 5
Edition
Express 499, Pro, Enterprise
Created by Sam Robbins.

While working with the Video Cloud App SDK for iOS and Cocoa Touch, there are some potential pitfalls that you can run into. This article will help keep you on the right track as you code your application. Also remember to review these other documents about the Video Cloud App SDK for iOS:

Memory management

A common problem area in programming for the iPhone is memory management. Since it is so important to making your app crash-free and usable, we will review the golden rules of memory management here. If you create an object with a method that contains new, alloc, or copy, you will need to release or auto-release that object later. There will also be times when you will need to take ownership of an object by calling the retain method. When you make a Video Cloud Media API call, the returned objects, like BCVideo, should be retained and then released when they are no longer needed. Debugging a memory issue can be painful, but if you develop applications carefully, run your code incrementally, and search online when you get stuck, you should be able to pinpoint your error. If you have Xcode 3.2 installed, the "Build and Analyze" build option in the Build menu can help you find potential memory-management issues in your application. The developer documentation from Apple contains more info on analyzing code.

Unit testing

Unit testing is a great way to make your applications more stable, and to see if your code does what you want it do. The Apple iOS SDK comes with the OCUnit framework, which provides all of the basic functionality you would expect in a unit-testing framework. There are plenty of third-party unit-testing frameworks for Objective-C, but one we recommend incorporating into your project is OCMock, which lets you mock parts of your application so it is easier to test.

Best Practices: Handling common error scenarios

You must enter an API token or the BCMediaAPI will throw an NSInternalInconsistencyException when you try to make a call.

BCMediaAPI *api = [[BCMediaAPI alloc] initWithReadToken: APIToken];

When making a call to the Video Cloud APIs, check if the result is nil. If it is, check the error pointer you passed in as a parameter.

BCMediaAPI *api = [[BCMediaAPI alloc] initWithReadToken: APIToken];

NSError *e;

BCVideo *video = [api findVideoById: 12345 error: &e];
if (video) {
    [video retain]; //video is defined so we retain it
} else {
    NSString *errStr = [api getErrorsAsString:e];
        NSLog(errStr);
}

If the object you are looking for is not found, i.e. if you call findVideoById with an invalid video ID, the result will be nil and the error will contain a "null" message. In the example below, video ID 121212 does not exist.

BCMediaAPI *api = [[BCMediaAPI alloc] initWithReadToken: APIToken];

NSError *e;

BCVideo *video = [api findVideoById: 121212 error: &e];
if (video) {
    [video retain];
} else {
    NSString *errStr = [api getErrorsAsString:e];
        NSLog(errStr); // Received error: null logged to the console
}

Handling unavailable network

Since your app is on the move with the user, network reliability can change at any time. If the user's device can't reach the Video Cloud service, the error pointer will be populated with an NSCocoaErrorDomain error.

BCMediaAPI *api = [[BCMediaAPI alloc] initWithReadToken: APIToken];

NSError *e;

BCVideo *video = [api findVideoById: 456123 error: &e];
if (video) {
    [video retain];
} else {
    NSString *errStr = [api getErrorsAsString:e];
    NSLog(errStr); // Received error: Operation could not be completed. (Cocoa error 256.) logged to the console
}

Playing invalid videos

If you try to play a video that is deactivated, invalid, inactive due to scheduling, or in an unaccepted state (which may apply to videos shared with media sharing), the video loads a blank black screen in the player UI. You should avoid playing a video that is in any of these states.

Playing streaming videos

If you try to play a streaming video, the Apple MPMoviePlayerController class will throw an exception:

Terminating app due to uncaught exception 'NSInvalidArgumentException', reason: 'Invalid content URL provided to MPMoviePlayerController (media url)'.

The RTMP and RTMPe protocols are not supported by the MPMoviePlayerController class. We suggest configuring your Video Cloud account to use Universal Delivery Service, so you can play your streaming content over HTTP. This example below shows how to turn on Universal Delivery Service support in the BCMediaAPI object.

BCMediaAPI *api = [[BCMediaAPI alloc] initWithReadToken: APIToken];
[api setUdsSupportOn:YES];

After that property is set, all Media API calls will be made with the media_delivery=HTTP argument appended.

More Tips and Tricks

No geo-restriction

Even though the BCMediaAPI object will return your media's geo-restriction metadata, geo-restriction is not supported in the MPMoviePlayerController. We hope to offer this in the future.

Region support

By default, all calls to the Video Cloud Media API go to api.brightcove.com, but you may elect to have them directed to api.brightcove.co.jp, instead. To do this, use the setRegion() method in the BCConfigManager class; the method takes a region enumerator value of either BCRegionUS or BCRegionJP.

Formats and encodings

Playing back videos with high resolutions can cause artifacts in the player. We recommend encoding low resolution renditions for mobile playback. If you are using our default transcoding settings, you are all set. Otherwise, you want to make sure your videos include a rendition encoded in H.264 baseline profile with a total bandwidth of approximately 256 kbps.

Trying to play an unsupported format — .flv and others — over HTTP will display an error alert. There is a known issue where the status bar will appear after the alert is dismissed.

iPhone SDK Twitter issue (for the deprecated library libBCiPhoneKit.a only)

The 1.x release of the Video Cloud App SDK for iOS uses Twitter's basic authentication for sharing videos on Twitter. In the future, Twitter will be turning off basic authentication in its API. As a result, until we can complete a new release of the Video Cloud App SDK for iOS that uses a different authentication API, sharing from Video Cloud apps for iOS to Twitter will stop working. To avoid sharing errors in your Video Cloud apps for iOS, you should:

  1. Update your already released iPhone app. In this new version, include this line to turn off the Video Cloud player's sharing menu:

    bcPlayer.shareMenuEnabled = NO; // this turns off the sharing menu item

    This line should be included wherever you create a BCPlayer instance.
  2. Compile your new app version and release it as an update of your app in the iTunes app store.

We hope these tips help you while you are developing your iPhone application using the Video Cloud App SDK for iOS. 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.

Tags
iOS, iPad, iPhone