Chapter 18: Selling Past the Sale with In App Purchases
The iOS SDK has helped many developers earn enough to make a living, and a variety of business models have helped these developers earn money. The first model is easy to understand (and arguably the most profitable): Make an app and sell it on the App Store. Another model is to release both a free lite version and a pro version of an app. Yet another model, probably pioneered by Web 2.0, is advertisement-based. Developers use a third-party advertiser’s SDK (or iAds) to show advertisements, and developers are paid for impressions or click-through. Although all these augment a developer’s earnings, the first model, selling apps on the App Store, has been by far the most successful model. In App Purchases augment this model by offering yet another unique way to sell premium contents or features on your iOS app. Some apps take advantage of this and make money only through in app purchases. They fall into a category called freemium apps, and they have been quite successful, at least when you look at the top-grossing apps list on U.S. App Store.
In this chapter, I introduce you to Apple’s In App Purchase framework, StoreKit.framework, and move on to a wrapper framework, the MKStoreKit, and discuss how to use it to integrate a mini–In App Store within your app. Then I provide you with solutions to the problems that developers most commonly face while integrating StoreKit within their app.
In iOS 6, Apple introduced a new feature where you can host your In App purchasable contents with Apple instead of a third-party server or your own server. This should help alleviate receipt validation issues. Later in this chapter, I show you how to set up a purchasable bundle for your app.
Before You Start
The chapter is divided into two major sections, the first half focusing on creating and customizing products on iTunes Connect and the second half focusing on the programming aspects. You’ll be using MKStoreKit, and I’ll be taking you through its features and showing you how to customize it for every possible business model (that Apple would approve). Throughout the chapter, you’ll look at the most common issues and problems faced by developers and solutions for getting around them. Pay special attention to the shaded boxes, which offer helpful tips and important warnings. The information in those boxes explains what can go awry during implementation if something isn’t done properly. So, now it’s time to start your journey.
In App Purchase Products
Products that can be sold using In App Purchases broadly fall under the following four categories: content, functionality, service, and subscription. The latest SDK provides support for all of them. Apple allows four different product types—namely, consumable, nonconsumable, auto-renewable subscriptions, and nonrenewable subscriptions. Now, match the following categories of products to the needs of your business model:
• Content—Products that are categorized as content include digital books, magazines, additional level packs, music, ringtones, and a variety of other data. Content can be either sold as consumable or nonconsumable depending on your business model. Thinking from the user’s perspective, content is generally considered nonconsumable. For example, when a user gets a book, it’s your responsibility as a developer to remember his purchase and make it available to him for free. The SDK, in most cases, provides this feature for free.
• Functionality—Products that are categorized as functionality mainly include locked features. For example, a task manager app can allow users to create a maximum of “n” tasks and to create tasks after that limit, the user has to unlock by paying a fee. Functionality is almost always considered nonconsumable. Apple rejects your app if you submit a functionality as a consumable.
• Services—Products that are categorized as services are mostly functionality that cause a recurring expense to the developer. Services are very similar to the functionality category, except that they involve serious computation power and are done on a remote server. A classical example of this is push notifications. A Twitter client, for example, may provide push notifications as a consumable selling, say 1,000 notifications for one dollar.
Services can also be subscriptions-based if your business model requires it to be so.
• Subscriptions—Products that are categorized as subscriptions are mostly content or service. Subscriptions are usually used to provide the said content or service over a period of time as opposed to the time of purchase. Subscriptions are of two types: auto-renewable subscriptions and nonrenewable subscriptions. Auto-renewable subscriptions should be used only for products that provide new content and should not be used for covering your running costs. For example, a Twitter client cannot provide unlimited push notifications as a subscription costing $0.99 every three months using auto-renewable subscriptions, although it’s perfectly fine to use nonrenewable subscriptions.
Treating a product as a consumable or a subscription or a nonconsumable is up to the business owner.
Subscriptions were originally available in iOS 3.0. But they were complicated to use, and the developer bore the burden of renewing and/or restoring them to other devices. As such, adoption was low, and very few developers used them. With iOS 4.3, Apple introduced a new kind of product called, auto-renewable subscriptions, where restoring and renewing subscriptions happens automatically and is taken care of by Apple. From now on, you should almost always use auto-renewable subscriptions. Use the older subscription style only if your business has proper server-side subscription handling in place that customers are already using.
Prohibited Items
In the previous section, I explained about the products that you could sell via In App Purchase. Although Apple is okay with most kinds of business models, you cannot sell certain items via App Store as of this writing.
Arguably the most important point to remember is that you cannot sell physical goods or services through In App Purchases. For example, if you develop a wallpaper app, you can sell digital wallpapers, but you cannot sell printed posters of the same wallpapers through In App Purchase. Similarly, if you’re a hotel owner and make an app for booking reservations, you cannot collect reservation fees or booking fees through In App Purchase.
The second kind of item that isn’t allowed is intermediate currency that expires. If you’re making a music subscription app, you can sell “points” and allow the user to download music for those points, but these points should never “expire”. Subscription passes, and pre-purchasable coupons are all allowed as long as they don’t expire.
Warning: There might be an app that already sells one of the prohibited items on App Store, but that doesn’t automatically entitle you to do the same. You’d be taking the risk of getting rejected by Apple later. If you see an app selling an item that is prohibited by rule, chances are it missed the review process.
Lotteries or sweepstakes are allowed in some cases, if the developer is permitted by law to run a lottery business. Again, you can sell those apps only in countries where you have the legal right to do so. Having a lottery app on the U.S. App Store doesn’t automatically entitle you to sell the same app on the U.K. App Store or the Australian App Store. You might need to submit additional documents to the Apple review process along with your app.
Apple’s developer documentation doesn’t contain information on what is allowed and what is not allowed. Read the App Store Review Guidelines at developer.apple.com and your iOS developer license agreement to understand what is and isn’t permitted.
Rethinking Your Business Model
All items that you’re planning to sell through In App Purchase (especially content) have to go through Apple’s formal review process, which usually take a week and sometimes longer. Remember this when coming up with your business plan.
If you’re making an app that provides premium wallpapers for download, you probably won’t be able to sell a “wallpaper of the day” through In App Purchases—at least not easily. You can, however, think of different business plans, like offering a free download for any wallpaper of the day if the user has subscribed to a premium membership. Another suggestion is to submit your app’s “wallpaper of the day” for at least the next 30 days so that you have full control of releasing it on the correct dates. Ensure that your buffer is longer than the worst-case approval times.
Finally, every product you submit to the App Store needs to be configured on iTunes Connect. This configuration might take anywhere from a couple of minutes to an hour (if complex screenshots are needed). If you’re selling digital books or any other digital content, like wallpapers, it might not be feasible (time wise) to configure every product on iTunes Connect. Moreover, there is a limit of 5,000 Stock Keeping Units (SKUs) that you can add to your product via In App Purchases. A recommended alternative in such a case is to make them consumable.
At this point, you’ve probably decided whether to sell your In App product as a consumable, nonconsumable, or subscription. Now, it’s time to move on to the next section, which is perhaps the most important section in App Purchases integration.
Setting Up Products on iTunes Connect
Implementing In App Purchases in your app is 20 percent configuration, 10 percent getting the right business model for your app, and 70 percent implementation. With MKStoreKit, that 70 percent coding reduces to somewhere near zero. However, the addition of new types of products has made configuration confusing, and changes to rules and lack of proper documentation on what is acceptable and what isn’t acceptable has made choosing the right business model difficult, so configuration remains the most challenging aspect of the integration.
This section walks you through the steps involved in setting up products on iTunes Connect. I assume that you’re already signed up with the iOS developer program and have the necessary credentials to log in to various portals like iOS developer program portal and iTunes Connect.
I refer to the iOS developer program portal and iTunes Connect throughout the next few pages. The following links will be of help. The URLs are pretty easy to remember: iOS developer program portal, developer.apple.com/devcenter/ios/index.action; and iTunes Connect, https://itunesconnect.apple.com/WebObjects/iTunesConnect.woa.
Step 1: Create a New App ID for Your App
Every app that requires In App Purchases needs an App ID that is unique to the application. The ID cannot include a wild card character (*). The recommended convention for this is reverse DNS notation. Here are a couple of examples:
com.mycompany.myapp.levelpack1
org.mycompany.myapp.levelpack2
To create a new App ID, log in to the iOS developer program portal and navigate to the iOS provisioning portal, as shown in Figure 18-1.
Click the New App ID button and follow the wizard to create an App ID. Ensure that you use a fully qualified App ID without any wild card characters.
Figure 18-1 iOS provisioning portal
Warning: A wild card character in your App ID will prevent you from adding products for In App Purchases later. If you already have a product on App Store and want to integrate In App Purchases in the next release, but the live app isn’t using a unique App ID, it will still work, but your users will not be notified about this update automatically through the App Store; they have to download it again. To push update notifications, App Store relies on the fact that subsequent updates to a product use the same App ID and incrementing version numbers. Although there are workarounds to associate a new App ID to an existing Bundle ID (Apple Technical Note QA1680), I still recommend using a unique product ID for each app you develop. As of this writing, with iOS 6, there are several features that rely on a unique App ID including but not limited to push notifications, Game Center integration, and iCloud integration. If your app might use any one of these features (even in a future release), use a unique App ID from the beginning.
Step 2: Generate Provisioning Profiles
In App Purchases can be tested on iOS Simulator version 5.1 and later; however, I highly recommend using a device to run and test In App Purchases. This means you need to create a provisioning profile for running your app on a device. The second step is to create a provisioning profile. Go to the fifth link from the left side of the navigation pane in the iOS Provisioning Portal. This step is exactly the same as for any other app. Remember to choose the same App ID that you created in the previous step.
Step 3: Create the App’s Product Entry
Before you create In App Purchase products, you need to have an app that sells your In App Purchase products. You start by creating an application on iTunes Connect. Open iTunes Connect and click Manage Your Applications. That’s the first link in the right column, as shown in Figure 18-2.
Figure 18-2 iTunes Connect home page
Create a new application from the Manage Your Applications link. It’s most important for you to choose your Bundle ID correctly. Choose the App ID you created in Step 1 as your Bundle ID here, as shown in Figure 18-3.
The Bundle ID and App ID are the same. Apple just uses a different name here.
Figure 18-3 New application form
Making a mistake in this step means that you will not be able to get detailed information about an In App Product programmatically later. The product identifiers will be returned as Invalid Product IDs, described later in this chapter. This is because your In App Purchase Products are tied to an app using the Bundle ID (App ID).
An app with a specific Bundle ID cannot sell In App Purchase Products that are meant for a different app that uses a different Bundle ID.
Step 4: Create the In App Purchase Product Entries
Click on the app, and you’ll see a screen like the one shown in Figure 18-4.
Figure 18-4 App information
Click the Manage In-App Purchases link to create your first In App Purchase Product.
If you don’t see the Manage In-App Purchases option on your iTunes Connect, be sure your iTunes Connect account has Admin privileges. Then check that your Contract Tax and Banking information is correct. If this is your first app and you haven’t yet submitted your tax documents and/or haven’t accepted the Paid Applications Contract, you will not see this link on the page. In that case, correct the situation appropriately and wait; Apple normally takes a week or two to approve your documents, depending on your location.
On the first page, you see four different types of products available for you to create. Choose the product type you’re creating (discussed earlier in the chapter) and proceed.
To create the Product ID for your In App Products, I recommend suffixing the product identifier with your Bundle ID. For example, if your Bundle ID is com.mycompany.myapp, your In App Product ID would be com.mycompany.myapp.inapp. This will ensure that Product IDs across your other apps don’t clash with each other.
Consumables, Nonconsumables, Non-Renewing Subscriptions
For all product types except auto-renewable subscriptions, you have to enter a product identifier and choose its price tier. Add a description that shows up when the user buys your product. If your product is multilingual, add descriptions in all supported languages in this page.
You now have to add a screenshot of the product (yes, that’s for the product you have not yet created) before you can submit the form. For the time being, upload a 320×480 iPhone screenshot. This screenshot is only for iOS App Store review purposes. In most cases, you need this only for content. For features or other consumables, it’s okay to upload a screenshot displaying the In App Store.
Non-renewing subscriptions are recommended since Apple announced the new auto-renewing subscriptions. Functionally, auto-renewing subscriptions offer everything that non-renewing subscriptions offer and add features like automatic renewal without user intervention, and restoring subscriptions on the customers’ other devices.
Auto-Renewable Subscriptions
Auto-renewable subscriptions are slightly different. You create a subscription family and add the duration of the subscription to that family. This allows you to create the same subscription for a magazine with different durations. For instance, you can create a weekly subscription at $5 or a monthly subscription at $20 or a yearly subscription at $300. Other options within a subscription family are similar to consumables.
Step 5: Generating the Shared Secret
For auto-renewable subscriptions, you need to take one more very important step: generate a shared secret.
On the App Information page (refer to Figure 18-4), click the Manage In App Purchases link. On this page, you’ll see a link titled View or Generate a Shared Secret. Copy the shared secret safely. You’ll need it when you write the real code.
Now that you have the products set up properly on iTunes Connect, it’s time to create some user accounts for testing.
Step 6: Creating Test User Accounts
Now create user accounts that you’ll use for testing In App Purchases after implementation. You can do this later, after implementation, but doing it now completes all the steps needed for configuring In App Purchases.
To create test user accounts, open the iTunes Connect home page (refer to Figure 18-2) and click Manage Users. You’ll see two links, one for creating an iTunes Connect user and another for creating a Test User. Click the second link and create a Test User. This should be fairly simple.
That completes the configuration part of In App Purchasing. If you’ve done all the steps correctly, you have completed 30 percent of the In App Purchase Integration. The remaining 70 percent is the real code, which you dive into next.
Step 7: Creating Hosted Content
Step 6 is the final step, unless you’re planning to host additional downloadable content with Apple, (which I highly recommend). Hosting content is available only for nonconsumables at the moment, and you can choose this option from iTunes Connect when you create your In App purchasable product, as shown in Figure 18-5.
Figure 18-5 Hosting content with Apple
After you do this, you have to create a subproject that signs your hosted content. You can do this in Xcode, as shown in Figure 18-6.
After you create the project, edit the file ContentInfo.plist and change the IAPProductIdentifier key to your In App Purchase product’s product identifier.
Figure 18-6 Creating a In App Purchase content project
Now, add the assets for this product into this project. You can add them from Finder or another Xcode project by dragging and dropping them. Build and Archive your project. You are all set now. You can submit this archive for App Store review using Xcode’s Organizer, much like the way you submit apps.
In App Purchase Implementation
The configuration of In App Purchases was a bit difficult, and so is the programming involved in the implementation. In App Purchase implementation requires you to complete some tedious coding. The following is a comprehensive list of the important tasks that you have to do for implementing In App Purchases in your app.
• First and foremost, your app could be closed (probably by a phone call) while a transaction is in progress. Given that transactions can continue outside of your app, you should have a Store Observer class that initializes at application launch and receives any purchases made while the app is in the background.
• Remember the actual number of consumable items purchased.
• Remember the nonconsumable purchase and allow the user to restore it on his other devices.
• Remembering these purchases should be done securely using iOS keychain.
• Post non-renewing subscriptions to your server and “remember” them there. You should also have the capability to restore them on any other device when the user logs in to your app from another device.
• Consumable contents can be occasionally delivered digitally from your server. In that case, your server should be able to verify the authenticity of the receipt and provide content. This also means that your iOS app should post App Store purchase receipts to your server before it starts downloading content.
• Verify whether auto-renewing subscription receipts are still valid. Even though auto-renewing subscriptions are renewed automatically without manual user intervention, you’re still required to check this because a user might have cancelled the subscription. A cancelled subscription remains valid only until the end of the current subscription period. This means that you as a developer need to remember purchases and purchase receipts, and you need to verify the receipts’ validity, probably during app launch. If they are no longer valid, stop providing the content.
• To validate auto-renewing subscriptions, post your receipt and the shared secret you generated in Step 5 of the previous section to the App Store, parse the returned JSON (JavaScript Object Notation), and get the subscription’s latest purchase date.
• The StoreKit.framework doesn’t tell you when an auto-renewable subscription ends. Instead, the API returns the actual date of the latest receipt. From this date, you need to calculate the actual date of expiry.
• Display localized product prices and descriptions on your Store View Controller.
Although this might sound complicated, MKStoreKit wraps most of these functionalities. Next, you see how to add MKStoreKit into your app and build it.
Introduction to MKStoreKit
MKStoreKit is an open source framework that makes integrating In App Purchases simpler. As of this writing, the latest version is 4.0, and this is the version used in this chapter.
Why MKStoreKit?
MKStoreKit automatically takes care of the following items in the list in the preceding section.
• When your app is closed while a transaction is in progress, MKStoreKit automatically tracks this, continues to observe StoreKit delegates, and remembers any purchases made outside your app. This takes care of the first item.
• For consumables and nonconsumables, MKStoreKit automatically remembers your purchases in the iOS keychain. Purchases are remembered using your product identifiers as the key, so in most cases, you don’t have to customize anything here. The second, third, and fourth items are thus taken care of automatically.
• The MKSKProduct class posts non-renewing subscriptions to your server. So, the fifth item is taken care of, if you do the server customization with the PHP code that comes with MKStoreKit. You learn about this later in the “Customizing MKStoreKit” section.
• For consumables or any content you deliver digitally from your server, you have to post the App Store receipt to your server. The server should verify the receipt and validate it. If the receipt is valid, it should deliver the content to your app. The MKSKProduct class takes care of this in tandem with some server configuration, which you learn about later in this chapter. This handles the sixth item.
• For auto-renewing subscriptions, you need to verify the latest receipt when your app is launched and disable access to content when the user has canceled the subscription. The MKSKSubscriptionProduct class does this automatically, including parsing the response JSON from the App Store and verifying that the subscriptions are still valid; it notifies you via NSNotificationCenter. You need to tell MKStoreKit how many days a subscription is valid. You learn how to do this later in this chapter. This takes care of the seventh, eighth, and ninth items.
• MKStoreKit has helper methods that return your product descriptions and price formatted in the local currency of the user. This takes care of the last item.
Customizing MKStoreKit to work with your app takes less than 25 lines of code. In some cases, it may be less than 10 lines of code.
Now, before you actually integrate the framework, it’s always good to know how it works internally, which the next section explains.
Design of MKStoreKit
MKStoreKit uses blocks instead of delegates to notify you about product purchases. (You learn more about blocks in Chapter 23.) Other notifications like subscription expiry are posted to NSNotificationCenter. The framework comprises a main singleton class, the MKStoreManager, and several other support classes listed here:
• MKStoreManager.h and MKStoreManager.m—This is the main singleton class that handles most of the implementation. You have to initialize this singleton in the AppDelegate’s applicationDidFinishLaunchingWithOptions: method.
• MKSKProduct.h and MKSKProduct.m—This is an internal class used by MKStoreKit to validate purchases. MKStoreManager uses this class to communicate with your server to check whether the receipt is valid and the actual product can be downloaded. This is used only for Server Product Model where you verify receipts on your server and deliver content digitally.
• MKSKSubscriptionProduct.h and MKSKSubscriptionProduct.m—This is another internal class used by MKStoreKit to validate your auto-renewable subscription purchases. MKStoreManager uses this class to communicate with your server to check whether the latest subscription receipts are still valid. If the user has cancelled his subscription, this class notifies MKStoreManager that the subscription is no longer valid, and MKStoreManager posts a notification. You have to observe these notifications (shown below) on your view controller and enable or disable your Subscribe buttons accordingly. If your app doesn’t use auto-renewable subscriptions, you don’t have to do this.
kSubscriptionsPurchasedNotification
kSubscriptionsInvalidNotification
• MKStoreKitConfigs.h and MKStoreKitConfigs.plist—These two files in the framework require customization based on your app. You’ll learn about customizing them later in this chapter.
• Remembering purchases—MKStoreKit uses iOS keychain to remember a purchase automatically when it’s purchased.
Customizing MKStoreKit
Here are two important files in MKStoreKit that you may be required to change:
MKStoreKitConfigs.h
MKStoreKitConfigs.plist
The plist file contains the list of products that you configured on iTunes Connect. You add your products under the corresponding keys in the plist depending on the product type. You add your consumables under the consumable key, nonconsumables under the nonconsumable key, and subscriptions under the subscriptions key. Every type of key has its own suboptions. You learn how to configure them later in this chapter.
Initializing MKStoreKit
Before you configure MKStoreKit, initialize it in your AppDelegate’s applicationDidFinishLaunchingWithOptions: method. This ensures that the StoreObservers are initialized properly to receive transactions completed outside of the app. Just initialize the singleton by calling the following in your AppDelegate:
[MKStoreManager sharedManager];
Though singletons initialize automatically when used for the first time, this call is still necessary when the app launches. Initializing MKStoreKit at launch ensures purchases made when the app was closed are received and stored when the app is opened again.
Configuring for Use with Server Product Model
When you sell content in your app and allow users to stream or download the content from your server, you use the server product model. In the server product model, the iOS app makes a purchase and sends the transaction receipt over to the server for verification. The server then verifies the receipt with Apple’s receipt verification server and, if the receipt is valid, redirects the request to the requested content.
Server Setup
MKStoreKit comes with server code in PHP ready to verify receipts from the server. Copy the Server Code directory and open it up for access. Copy the public URL for this directory. Let’s just assume that it can be accessed at this location:
http://api.example.com/servercode
Now go back to your iOS source, open the file MKStoreKitConfigs.h, and locate these lines:
#define SERVER_PRODUCT_MODEL 0
#define OWN_SERVER nil
#define REVIEW_ALLOWED 1
Set the OWN_SERVER value to @”http://api.example.com/servercode”.
You are all set. MKStoreKit will ping the featureCheck.php endpoint in this directory to verify receipts and remember the purchase only when the server says receipts are valid. Receipt validation is done by posting the receipt to Apple’s receipt validation URL:
https://buy.itunes.apple.com/verifyReceipt
For sandbox testing, you use
https://sandbox.itunes.apple.com/verifyReceipt
The server code automatically switches this based on the configuration you defined. The default implementation of featureCheck.php returns plain strings—YES or NO—based on whether the receipts are valid or not. You might need to modify it to return in JSONs along with the URL of the content location.
Configuring for Use with Consumables
In a generic sense, a consumable is a product that depletes as it is used. Printer ink is a common example. In App Purchases consumables behave the same way. When a user purchases a consumable product, it’s stored on the device and stays there until he uses it up. You’re not obliged to restore consumables on other devices. When implementing consumables, you often encounter a business case where bulk purchases are subsidized to the user, just like real-world consumables.
For example, you might have two products in your game, a small box of ammo containing one hundred bullets at $0.99, and a larger box containing a thousand at $5.99. Within your game, both the products are synonymous. However, SKU-wise, they are treated differently, and their cost is different. To implement this model, MKStoreKit allows you to specify names for your products. That way, you can tell MKStoreKit to treat them separately during purchase but treat them the same when consumed. Essentially, this means that buying either of the products increases the count of the same item. To configure MKStoreKit this way, use the suboptions inside the consumable key in MKStoreKitConfigs.plist, as illustrated in Figure 18-7.
Figure 18-7 Configuring consumables in MKStoreKit
You add the product ID of every consumable within the Consumables dictionary. Every product has a Name and Count. Assume you have two products: com.myapp.mygame.ammopackSmall and com.myapp.mygame.ammopackLarge. The “Count” key will let you set the count of the virtual consumable for this product purchase. The “Name” key will let you set the real name of the consumable. MKStoreKit normally remembers purchases with a product ID. But for consumables, it uses the “Name” key because multiple SKUs can actually mean the same product within your app.
Now, in the course of your game/app, if the user “consumes” your product, you first check if it’s available by calling the methods
- (BOOL) canConsumeProduct:(NSString*) productName quantity:(int) quantity;
- (BOOL) consumeProduct:(NSString*) productName quantity:(int) quantity;
consumeProduct will properly deduct the quantity of the product consumed from the purchased quantity and store the remaining available quantity in the keychain, all automatically.
Configuring for Use with Auto-Renewable Subscriptions
Auto-renewable subscription configuration is very similar to consumables configuration. The first step is to specify your shared secret. Copy the shared secret you generated earlier in the chapter and paste it here in the file MKStoreKitConfigs.h:
#warning Shared Secret Missing Ignore this warning if you don’t use auto-renewable subscriptions
#define kSharedSecret @”<FILL IN YOUR SHARED SECRET HERE>”
You can now remove the #warning line. Also, if you don’t use auto-renewable subscriptions (and thus don’t have a shared secret), you can ignore this warning. Just remove the #warning line.
Open the plist file, and as you would for consumables, instead of specifying the count, specify the duration of the subscription. Now, on your view controllers that display the store, observe the kSubscriptionsPurchasedNotification and/or kSubscriptionsInvalidNotification and enable or disable your subscribe buttons accordingly.
Making the Purchase
Now that you have configured MKStoreKit, making the real purchase is very simple. It’s just a single method call like this:
[[MKStoreManager sharedManager] buyFeature:@”com.myapp.myfeature”
onComplete:^(NSString*) purchasedProduct
{
// provide the content for the product “purchasedProduct”.
}
onCancelled:^
{
// optionally display an error
}];
After you configure MKStoreKit properly, it takes just a single method call to initiate a purchase. Remembering the purchase is automatically done for you. To check if a product has been purchased previously, you can call this method:
[MKStoreManager isProductPurchased:@”com.myapp.feature1”];
This returns a Boolean that states whether the product is purchased or not. Restoring purchases is done with another one-liner. Read the MKStoreManger.h file to see the functionalities exposed by MKStoreKit.
Now that’s fewer than 10 lines to get it all running, and maybe another 15 lines of configuration, as I promised at the beginning of the chapter.
Downloading Hosted Content
You set a handler method, hostedContentDownloadStatusChangedHandler, to update the UI that shows the download statuses of your user’s purchases.
[MKStoreManager sharedManager].hostedContentDownloadStatusChangedHandler = ^(NSArray*
hostedContents) {
// Update your UI here. This includes updating your download progress and
statuses. The hostedContents is an array of SKDownload objects and each object
has an identifier, download state and download progress.
};
The best part of hosted content is that you don’t have to worry about receipt validation on your server, and you don’t have to bother about encrypting your content and getting associated export licenses or depend on a third-party provider like Urban Airship to host your content. The downside is Apple’s approval process. Again, if your products change every day, like daily wallpaper, you might have to submit enough products to the queue so that your app has some content to purchase despite Apple’s long approval times.
Testing Your Code
Now that you have implemented In App Purchasing, go ahead and test whether your code works. You’ll need the credentials of the test user account you created earlier in this chapter for testing. Before you start, open the settings app on the device you’ll be using for testing and tap the Store menu. Log out of the App Store and ensure that no user is logged in to the store.
Run the app on a device and initiate a purchase. You’re prompted to enter or create a new iTunes account or use an existing account. Choose to use an existing account and enter the test username and password you created previously. App Store will now ask you to confirm the purchase of your In App Purchase Product. Tap on Buy (or subscribe), and your product is now purchased. You have successfully completed the In App Purchase integration in your app.
All this sounds good, but what happens when there is a problem? You see some quick troubleshooting techniques in the next section.
Troubleshooting
Despite all the explanation provided in this chapter, In App Purchases remains one of the most difficult frameworks to troubleshoot.
Invalid Product IDs
The most common problem is that App Store returns your product as invalid. If you have been following the chapter closely, reading every tip and warning, you shouldn’t encounter an invalid product ID. However, the problem could happen if you have any of the following issues:
• The product Bundle ID in the Info.plist file doesn’t match the App ID you created.
• Your contract and tax statements are not yet submitted and/or you have not yet accepted the iOS developer Paid Applications Contract. To correct these issues, go to iTunes Connect and click the Contracts, Tax, and Banking link. It’s very important to check this when you submit your first app.
• Jailbroken devices sometimes don’t work well with the App Store. An app called AppSync from Cydia seems to be the cause of most problems associated with In App Purchasing. In App Purchases are best tested with a device running an unmodified operating system.
Sometimes, even after you ensure that none of these issues is a problem, the App Store still indicates that your products are invalid. This happens more often to non–U.S.-based developers. Wait several hours before retrying (see “Retrieving Store Information” in the Apple Developer Documentation, 2011). Apple uses distributed servers, and it might take several hours to migrate the products you created from the U.S. servers to other mirror servers near your country.
Cannot Connect to iTunes Store
The other common problem is when you get the message “Cannot connect to iTunes store: Code: -1003.” This happens when your firewall blocks iTunes. Test the In App purchases by connecting to a different network or ensure that you have proper Internet connectivity.
You Have Already Purchased This Product, but It’s Still Not Downloaded
This error is common when you work with consumables. It happens mostly when you tap on the Buy button too often. The workaround is to disable the Buy button once the purchase is initiated and reenable it after the transaction completes. Follow the interaction pattern similar to the built-in App Store.
If your problem is still not solved, the old school method of deleting the app and redoing all the steps often works.
Summary
In App Purchases, although tricky to implement, offer an innovative and unique way to monetize your apps. Carefully deciding on your business model and implementing In App Purchases can vastly increase the money you make from the App Store. A quick look at the top grossing apps on U.S. App Store shows that at least 25 percent follow the freemium model whereby the app is free but content and features are provided through In App Purchases. This clearly proves that freemium is successful on App Store. With frameworks like MKStoreKit minimizing your coding efforts, why not give it a try?
Further Reading
Apple Documentation
The following documents are available in the iOS Developer Library at developer.apple.com or through the Xcode Documentation and API Reference.
App Store Review Guidelines
In App Purchase Programming Guide
Retrieving Store Information
Blogs
MKBlog. “iPhone Tutorial: In App Purchases”http://blog.mugunthkumar.com/coding/iphone-tutorial-–-in-app-purchases
MKBlog. “MKStoreKit 4.0 — Supporting Auto Renewable Subscriptions”http://blog.mugunthkumar.com/coding/mkstorekit-4-0-supporting-auto-renewable-subscriptions
Other Resources
MugunthKumar / MKStoreKit https://github.com/MugunthKumar/MKStoreKit