In-App Purchase Tutorial

In-App Purchase is a great tool for sales setup if you offer additional functionality or features to your iPhone application. But it’s not that easy to get the job done…

Here are some key tips for working with In-App Purchase that will help you add your products to the AppStore.

– In-App Purchase Process

– Purchased Products Types in the In-App Purchase

– Model of Server – Application Interaction in the In-App Purchase

– Pitfalls in Choosing Purchase Types in the In-App Purchase

– In-App Purchase Sample Code and Implementation

– Creating the Purchase Product and Test User

In-App Purchase Process

The connection with the Appstore has carried out through the StoreKit framework that is delivered with SDK starting from the 3.0 version. The core steps of the process are:

• the developer using itunesconnect.apple.com creates some virtual product with a name, description, and price
• the application connects to the Appstore and purchases the virtual product
• the application makes required changes or/and does certain actions (unlocks particular levels, makes a sound, enables monthly subscription for access to the information storage, magazine archive, etc. )

Purchased Product Types in the In-App Purchase

There are three types of products you can create:

• Consumable
• Non-Consumable
• Subscription

Consumable. According to the type name, the product can be purchased several times. For example, arrows or bullets for a game.
Non-Consumable. Someone can do only one purchase. This type of purchase is used to unlock new themes, additional levels, and so on.
Subscription. Subscription to any kind of service. This type can be used for a web service app to purchase a monthly premium account. Product of this type must be supported by different devices and users can make entries using one account.

Note! StoreKit framework offers tools to get transactions history, but the history will contain only the Non-consumable products transactions. For other types of products, create or use another server to store this information.

Model of Server – Application Interaction in In-App Purchase

A model of the server interaction can be described in the next 8 key steps:

• The application requests the list of the products from your server
• The app displays the list of the new products to the user
• The user either purchases the product or doesn’t buy it
• The app requests the purchase from the Apple’s server using StoreKit
• StoreKit sends the answer as a transaction
• iPhone application sends to its server a so-called receipt
• Application’s server validates the receipt on Apple’s server
• The iPhone app downloads the product from its server

Pitfalls in Choosing Purchase Types in the In-App Purchase

Apple is rather strict about the purchase type you’re using for the application.

If the developer has an intention to create a monthly subscription for current updates (let’s say to get new jokes from the web) but has no desire to implement the support for the range of devices, then he can’t use this purchase type. The Subscription type forces you to implement the support of many devices though Apple doesn’t provide any tools to facilitate this part of development.

The Consumable type seems to be a simple decision to make in such a situation: it doesn’t require device support and it’s easy to use. BUT: when trying to get project approval from Apple you’ll face rejection as Purchase doesn’t correspond application’s logic and confuses the user. Thus, if there is any hint on Subscription logic (or Apple can see it) the developer is forced to implement all the necessary features.
The uncertain regulation provided by Apple is the pitfall for the developers who are trying to estimate the application with In-App Purchase but have never had a deal with it before.

The best way out is to follow the implementation model provided by Apple. If it’s said in Apple’s docs “We recommend you to…” you should read “Implement the application this way only… or else…”

In-App Purchase Sample Code and Implementation

Here is an example of the In-App Purchase implementation structure for a simple case

Pic. 1. Architecture of the Update Unit

Here we have an application that has one product of the subscription type that gives you the opportunity to update twice a month. The application is free but has no trial period. Instead of the trial period, the app has some firmware that lets you use the app without purchasing the updated subscription.

|The Updater is a class whose task is to download and set up updates for the application. Before each update, it checks for the updates permission. To perform this, the Updater refers to the Local Storage.

Local Storage is an abstract and optional unit that stores information about subscription starting and expiry dates (preferably codified) locally. Local Storage is made to save some traffic and secures the situation when the billing server is unavailable.

If the Local Storage has no information, the Updater decides if it is possible to reinstall the app and refers to the AccountManager. The AccountManager returns all the required information or starts the registration or log in process.

When the date information is obtained the confirmation is carried on. If the subscription isn’t expired, then the update is performed otherwise and the request to InAppPurchaseManager takes place. The update purchase is offered to the user. Then using the StoreKit framework tools the InAppPurchaseManager carries on the transaction and returns the result to Updater. The Updater sends the receipt to the BillingServer to validate it. After successful validation Updater gets a new subscription date, saves it to Local Storage, and updates the information.

We can’t put here all the listings of the LocalStorage and AccountManager as their code will require dozens of pages. But we give you an In-App Purchase sample code from the real project where it was called InAppPurchaseController.

//-----------InAppPurchaseController.h--------------

#import <Foundation/Foundation.h>

#import <StoreKit/StoreKit.h>

@class inAppPurchaseController;

This class interconnects with the Updater using a protocol that sends messages when the info about the product and payment transaction (or error) is uploaded (otherwise the error occurs).

@protocol inAppPurchaseControllerDelegate

- (void) purchaseController: (inAppPurchaseController *) controller didLoadInfo: (SKProduct *) products;

- (void) purchaseController: (inAppPurchaseController *) controller didFailLoadProductInfo: (NSError *) error;

- (void) purchaseController: (inAppPurchaseController *) controller didFinishPaymentTransaction: (SKPaymentTransaction *) transaction;

- (void) purchaseController: (inAppPurchaseController *) controller didFailPaymentTransactionWithError: (NSError *) error;

@end

strPurchaseId is the class property that implies the work with the single product at the instant moment. The class can get the Product description and then purchase it.

@interface inAppPurchaseController : NSObject <SKProductsRequestDelegate, SKPaymentTransactionObserver>
{
 NSString   *strPurchaseId_;
  id <inAppPurchaseControllerDelegate>   delegate_;
}

@property(assign) id <inAppPurchaseControllerDelegate> delegate_;
@property(copy) 	NSString    *strPurchaseId_;

- (void)    loadProductsInfo;
- (void)    makePurchase: (SKProduct *) product;
- (BOOL) isPresentNonFinishedTransaction;

@end

//-------	InAppPurchaseController.m-----------

#import "inAppPurchaseController.h"

@implementation inAppPurchaseController

@synthesize strPurchaseId_;
@synthesize delegate_;

With the initialization, the class subscribes to messages from SKPaymentQueue. There is a payments queue where the query is sent to.

- (id) init

{

if(self = [super init])

{

[ [SKPaymentQueue defaultQueue] addTransactionObserver: self];

}

return self;

}

- (void) loadProductsInfo

{

SKProductsRequest *request = [ [SKProductsRequest alloc] initWithProductIdentifiers: [NSSet setWithObject: strPurchaseId_]];

[request setDelegate: self];

[request start];

}

Before the payment transaction is added to the queue, it’s necessary to check whether it can be done at the moment. Which is implemented by the call of the canMakePayments method from the class SKPaymentQueue.

- (void) makePurchase: (SKProduct *) product

{

if(![SKPaymentQueue canMakePayments])

{

[delegate_ purchaseController: self didFailPaymentTransactionWithError: [NSError errorWithDomain: @"payMentDomain" code: 123 userInfo: [NSDictionary dictionaryWithObject: @"can not make paiments" forKey: NSLocalizedDescriptionKey]]];

}

SKPayment *payment = [SKPayment paymentWithProduct: product];

[ [SKPaymentQueue defaultQueue] addPayment: payment];

}

- (BOOL) isPresentNonFinishedTransaction

{

NSArray *arrTransactions = [ [SKPaymentQueue defaultQueue] transactions];

for(SKPaymentTransaction *transaction in arrTransactions)

{

if([transaction.payment.productIdentifier isEqualToString: strPurchaseId_])

{

if(transaction.transactionState == SKPaymentTransactionStatePurchasing)

{

return YES;

}

else if(transaction.transactionState == SKPaymentTransactionStateFailed)

{

[ [SKPaymentQueue defaultQueue] finishTransaction: transaction];

}

}

}

return NO;

}

#pragma mark ---------------request delegate-----------------

- (void)requestDidFinish:(SKRequest *)request

{

}

- (void)request:(SKRequest *)request didFailWithError:(NSError *)error

{

[delegate_ purchaseController: self didFailLoadProductInfo: error];

}

When getting the products list we check if it is in the products array and the according result is sent as the message to the delegate.

- (void)productsRequest:(SKProductsRequest *)request didReceiveResponse:(SKProductsResponse *)response

{

NSArray *invalidIdentifiers = [response invalidProductIdentifiers];

NSArray *products = [response products];

for(SKProduct *product in products)

{

NSString *strId = product.productIdentifier;

if([strId isEqualToString: strPurchaseId_])

{

[delegate_ purchaseController: self didLoadInfo: product];

return;

}

}

if([invalidIdentifiers count])

{

[delegate_ purchaseController: self didFailLoadProductInfo: [NSError errorWithDomain: @"purchaseDomain" code: 143 userInfo: [NSDictionary dictionaryWithObject: @"No Products found" forKey: NSLocalizedDescriptionKey]]];

}

}

#pragma mark -------------------transaction observer-------------------

This method is called for every transaction status change. The product is considered purchased when the transaction status is equal SKPaymentTransactionStatePurchased.

- (void)paymentQueue:(SKPaymentQueue *)queue updatedTransactions:(NSArray *)transactions

{

for(SKPaymentTransaction *transaction in transactions)

{

SKPayment *payment = [transaction payment];

if([payment.productIdentifier isEqualToString: strPurchaseId_])

{

if(transaction.transactionState == SKPaymentTransactionStatePurchased)

{

[delegate_ purchaseController: self didFinishPaymentTransaction: transaction];

[queue finishTransaction: transaction];

}

else if(transaction.transactionState == SKPaymentTransactionStateFailed)

{

[delegate_ purchaseController: self didFailPaymentTransactionWithError: [NSError errorWithDomain: @"purchaseDomain" code: 1542 userInfo: nil]];

[queue finishTransaction: transaction];

}

}

}

}

- (void)paymentQueue:(SKPaymentQueue *)queue removedTransactions:(NSArray *)transactions

{

}

- (void) dealloc

{

[ [SKPaymentQueue defaultQueue] removeTransactionObserver: self];

[super dealloc];

}

@end

Creating the Purchase Product and Test User in iTunes Connect

You should enter ‘Manage Your In-App Purchases->Create New’ in iTunes Connect then choose the required application.

Choose Bundle ID and fill in the information about the Purchase (type, name, price, etc.). You should define ‘Product ID’ that can be of any kind but we advise you to use Reverse DNS. The best name for Product ID is the combination of the Bundle ID of your app and the feature’s name.

To test the In-App Purchases you should have at least one Test User. Go to ‘Manage Users->In App Purchase Test User’ and choose ‘Add New User’. Fill in the information about the user. Test User e-mail doesn’t have to be real.

That’s all. Wish you successful testing!

Hope this information was useful for you. If you’ve got questions about In-App Purchase or about Objective C programming, leave it as a reply and we’ll answer them as soon as possible.

Author: iPhone Development Department.