Best Practices for Developing Brightcove Apps for iOS

While working with the  Brightcove 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  Brightcove App SDK for iOS:

• Getting Started with the Brightcove App SDK for iOS
• iPhone Native Application
• Brightcove App SDK for iOS Reference
• Known Issues for the Brightcove 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 autorelease 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 Brightcove 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 Brightcove 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 Brightcove 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 Brightcove 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.

Formats and encodings

Playing back videos with high resolutions can cause artifacts in the player. We recommend encoding low resolution renditions for mobile playback; see our Encoding and Delivering Video to the iPhone article for more details.

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 SDK only, libBCiPhoneKit.a)

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

1. Update your already released iPhone app. In this new version, include this line to turn off the Brightcove 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  Brightcove App SDK for iOS. If you need help or have a question, please visit our forums. You can also follow the  Brightcove App SDK for iOS on Twitter: http://twitter.com/bciphonesdk.