In App Purchase Client Library - iOS

Overview

Urban Airship’s In App Purchase library provides a drop-in user interface for our In App Purchase API.

Our default user interface, StoreFront, handles displaying your content and descriptions to the user, as well as handling rotation, managing downloads, updates and purchase history.

Download

In App Purchase is available in two parts: a static library and an optional StoreFront sample implementation.

We recommend everyone download the latest stable version.

Libary: http://com.urbanairship.filereleases.s3.amazonaws.com/libUAirship-latest.zip

Sample App: http://com.urbanairship.filereleases.s3.amazonaws.com/IAPSample-latest.zip

If you’re feeling brave you can download the latest development version of all our iOS code or you can check the code out with git:

git clone git://github.com/urbanairship/ios-library.git

The library and sample app are completely open source, so you may modify them as you wish. Patches and pull requests are always welcome.

Upgrade from a Previous Version

If you are currently using a 2.1.x or earlier version of the StoreFront sample application, there are several changes you must make to your application in order to upgrade. The first step is to make a backup of your current project. Once your project has been backed up, you’ll remove the old Urban Airship code, install the new code and make some simple changes to the project and your code.

Install libUAirship

First, delete the Airship directory from your current project. Ensure that you delete the files from the disk and not just the project references. Next, download and unzip the latest version of libUAirship. Copy the Airship directory into your project folder:

cp -r Airship /SomeDirectory/YourProject/

Now inside of XCode, import the source files into your project.

Update your Project Target

StoreFront requires your application to link against some additional frameworks:

libUAirship.a (Add Other, then locate "libUAirship-1.0.0.a" in the Airship directory)
CoreTelephony (Exists in iOS 4+ only, so make it a weak link for 3.x compatibility)
libsqlite3
Security.framework
QuartzCore

You may need to make some other changes to your project. See Build Settings for details.

Update Code References

All Urban Airship classes are now prefixed with “UA”. You will need to update any imports and references to the old classes and headers.

Relevant changes include:

• Airship is now UAirship
• StoreFront is now UAStoreFront
• StoreFrontDelegate is now UAStoreFrontDelegate
• StoreFront UI functionality is now defined in UAStoreFrontUIProtocol

Update Airship Integration

Recommended changes to your app delegate in applicationDidFinishLaunching:withOptions

Set the UI class (do this first):

//Set custom UI
[UAStoreFront useCustomUI:[UAStoreFrontUI class]];//UAStoreFrontUI is the sample implementation

The takeOff method now takes a NSDictionary of configurable options and your application key and secret are now specified in a configuration file named AirshipConfig.plist. See The AirshipConfig File for details.

//Init Airship launch options
NSMutableDictionary *takeOffOptions = [[[NSMutableDictionary alloc] init] autorelease];
[takeOffOptions setValue:launchOptions forKey:UAirshipTakeOffOptionsLaunchOptionsKey];

// Create Airship singleton that's used to talk to Urban Airhship servers.
// Please populate AirshipConfig.plist with your info from http://go.urbanairship.com
[UAirship takeOff:takeOffOptions];

The displayStoreFront and quitStoreFront helper methods have been removed from Airship. To show StoreFront:

// Recommended way to present StoreFront. Alternatively you can open to a specific product detail.
//[UAStoreFront displayStoreFront:self withProductID:@"oxygen34"];
[UAStoreFront displayStoreFront:self animated:YES];

    // Specify the sorting of the list of products.
[UAStoreFront setOrderBy:UAContentsDisplayOrderPrice ascending:YES];

From the old sample view controller, it was possible to disable the Done button during downloads in the [StoreFrontSampleViewController shop] method:

// Optional if you want to disable the "Done" button in StoreFront while
// there are active downloads.
[StoreFront shared].downloadsPreventStoreFrontExit = YES;

This has been moved to the sample project in [UAStoreFrontViewController refreshExitButton]:

// Optional if you want to disable the "Done" button in StoreFront while
// there are active downloads, just directly set:
self.navigationItem.leftBarButtonItem.enabled = YES

Update your Custom UI

If you are using a custom UI, you will need to refactor it to conform to the following protocols:

UAStoreFrontUIProtocol
UAStoreFrontDelegate
UAStoreFrontAlertProtocol
UAProductObserverProtocol
UAStoreFrontObserverProtocol

Example implementations of these protocols can be found in the StoreFront sample application.

Other Upgrade Notes

Download directories have changed from NSDocumentsDirectory to NSLibraryDirectory by default.

Accessing Downloaded Content

Downloaded content is decompressed into your application’s Library directory. In previous versions, the default download location was the Documents directory. You will need to handle this change in your application.

NSString* docsDir = [NSSearchPathForDirectoriesInDomains(
    NSLibraryDirectory, NSUserDomainMask, YES) objectAtIndex:0];

Set Up a New Application

Copy libUAirship Files

Download and unzip the latest version of libUAirship. If you are using the sample project, copy the Airship directory into the same parent directory as your project:

cp -r Airship /SomeDirectory/ (where /SomeDirectory/YourProject/ is your project)

If you are not using the sample project, you’ll need to import the source files into your project:

Required Libraries

StoreFront requires your application to link against the following Frameworks:

libUAirship.a
CFNetwork.framework
CoreGraphics.framework
Foundation.framework
libz.1.2.3.dylib
MobileCoreServices.framework
StoreKit.framework
SystemConfiguration.framework
UIKit.framework
CoreTelephony (this is iOS 4.x only, so make it a weak link for 3.x support)
libsqlite3
Security.framework
QuartzCore

Build Settings

Compiler

Your project should use the GCC compiler (the default). LLVM is not supported at this time.

Header search path

Ensure that your build target’s header search path includes the Airship directory.

Linker

In order to properly link against the Urban Airship static library, you will need to set the -all_load flag in your build target’s Other Linker Flags.

Airship API Setup

First, place your development and production keys and secrets in a file named AirshipConfig.plist. See The AirshipConfig File for details.

Inside your application delegate’s applicationDidFinishLaunching:application method initialize a shared UAirship instance.

//Init Airship launch options
NSMutableDictionary *takeOffOptions = [[[NSMutableDictionary alloc] init] autorelease];
[takeOffOptions setValue:launchOptions forKey:UAirshipTakeOffOptionsLaunchOptionsKey];

// Create Airship singleton that's used to talk to Urban Airship servers.
// Please populate AirshipConfig.plist with your info from http://go.urbanairship.com
[UAirship takeOff:takeOffOptions];

Then from the view controller from which you wish to spawn StoreFront call the following method to launch it. In the example below self refers to your view controller.

[UAStoreFront displayStoreFront:self animated:YES];

Setting properties of UAStoreFront will customize its behavior. This is optional.

[UAStoreFront setOrderBy:UAContentsDisplayOrderPrice ascending:YES];
[UAStoreFront shared].downloadsPreventStoreFrontExit = YES;

StoreFront Delegate

StoreFront will notify your class of interesting StoreFront events - just implement the UAStoreFrontDelegate protocol in your class and register it as a delegate.

Register class as delegate:

[[UAStoreFront shared] setDelegate:self];

Example UAStoreFrontDelegate methods:

#pragma mark -
    #pragma mark StoreFrontDelegate

    -(void)productPurchased:(UAProduct*) product {
        UALOG(@"[StoreFrontDelegate] Purchased: %@ -- %@", product.productIdentifier, product.title);
    }

    -(void)storeFrontDidHide {
        UALOG(@"[StoreFrontDelegate] StoreFront quit, do something with content");
    }

    -(void)storeFrontWillHide {
        UALOG(@"[StoreFrontDelegate] StoreFront will hide");
    }

    - (void)productsDownloadProgress:(float)progress count:(int)count {
        UALOG(@"[StoreFrontDelegate] productsDownloadProgress: %f count: %d", progress, count);
        if (count == 0) {
            UALOG(@"Downloads complete");
        }
    }

The StoreFront example code provides a sample implementation of the UAStoreFront delegate inside StoreFrontSampleAppDelegate.

Accessing Downloaded Content

Downloaded content is decompressed into your application’s Library directory. Unfinished download will be automatically resumed when re-entering StoreFront.

NSString* docsDir = [NSSearchPathForDirectoriesInDomains(
NSLibraryDirectory, NSUserDomainMask, YES) objectAtIndex:0];

The Sample User Interface

When a user launches StoreFront the first thing they will see is the Content screen. This screen displays some basic information about the content, with a search bar on the top.

If the user selects something from the Content screen they are then taken to a more detailed view of the product with a full description and purchase button.

Once a user has selected content to purchase it is added to the Installed tab and a progress bar is shown for each downloads.

If a purchased item has been updated, its pricing label will become UPDATE, and the item will also be listed in Updates tab. If more than 1 item has been updated, a Update All button will be available on upper right of the screen

You can also use StoreFront for your iPad apps. The StoreFront interface takes advantage of the iPad’s larger size, and displays the Content and Product Detail screens together in split-screen in both landscape and portrait orientation.

Localization

StoreFront has built-in localization support and provides English and Chinese samples. All Urban Airship localization strings for StoreFront are contained in their own bundle:

UAStoreFrontLocalization.bundle

To add a new translation just copy one of the existing lproj directories into the bundle and update all of the items in Localizable.strings

Uploading Your Content

To upload content to appear in your StoreFront first log in to:

http://go.urbanairship.com/

Once you’ve logged in click on Manage in-app content from the navigation links and proceed to Add new in-app content

The product id specified must match exactly the product identifier you specified for your in app content inside of iTunes Connect. If StoreFront does not find a corresponding product in iTunes Connect the content will not be displayed in the StoreFront interface (with the exception of Free content).

Compressed content must be in a .zip format. StoreFront does not currently support any other types of compression.