Using the iOS In-App Purchase Service

From RAD Studio
Jump to: navigation, search

Go Up to Creating an iOS App


In-app payment services let you sell digital content directly within your applications. iOS In-App Purchase is the iOS in-app payment service. This topic describes how to give your applications access to iOS In-App Purchase using FireMonkey.

Note: Read iOS Mobile Application Development before you continue. The following information complements the main documentation topic about iOS development.

Supported Devices

FireMonkey supports iOS In-App Purchase on any supported iOS device.

Note: The iOS simulator is not supported.

Prerequisites

Before you can use the iOS In-App Purchase service, in addition to preparing your development environment:

Configuring Your Application for In-App Purchase in iTunes Connect

To be able to use and test the iOS In-App Purchase service in your application, you must first create an entry for your application in iTunes Connect.

Once you have an entry for your application, open the App Summary page of your application in the Manage Your Apps module of iTunes Connect, and click Manage In-App Purchases on the right-hand side of the App Summary page.

On the page that opens you can manage In-App Purchase for your application. For example, you can create In-App Purchase products to sell in your application.

TInAppPurchase supports consumable and non-consumable in-app purchase products. See About In-App Purchase Products for more information about these product types.

Note: Subscription-based types are not currently supported.

Adding iOS In-App Purchase Support to Your Mobile Apps

You need to add an instance of this component to your application, and establish a connection to the target in-app payment service either when your application starts or at any other point. Then you can use the service. Once you establish a connection to your in-app payment service, you can:

Establishing a Connection to Your In-App Payment Service

Before you can use your in-app payment service, you must configure TInAppPurchase to connect to your in-app payment service and establish a connection.

Configuring the Connection Data for Your In-App Payment Service

To connect to the iOS In-App Purchase service on iOS, TInAppPurchase does not need any special configuration and should work, provided that your application:

Connecting to Your In-App Payment Service

To connect to the target in-app payment service, call SetupInAppPurchase. This procedure is asynchronous, and once it finishes it triggers the OnSetupComplete event. If you want to associate an event handler to OnSetupComplete, do it before you call SetupInAppPurchase: 

InAppPurchase1.OnSetupComplete := InAppPurchase1SetupComplete;
InAppPurchase1.SetupInAppPurchase;

You usually want to associate OnSetupComplete to an event handler, to request the list of products as soon as you are connected to the target service. Alternatively, you can call IsSetupComplete to check whether you can use the service at a particular time (True) or not (False).

Using Your In-App Payment Service

Once you have established a connection to your in-app payment service, you can do any of the following:

Obtaining Information About a List of Products

Your application should keep a list with the IDs of the products that can be purchased from your application. Keep this list in the TInAppPurchase.ProductIDs property. You can call QueryProducts at any time to request information about the products with these IDs, such as whether these products have been purchased or not.

If there is an error, TInAppPurchase.OnError is triggered with ProductsRequest as FailureKind.

If the request is successful, TInAppPurchase.OnProductsRequestResponse is triggered instead. This event provides two lists of products:

  • Products, a TList of instances of TProduct that provides the list of valid available and purchased products.
  • InvalidProductIDs, a TStrings that provides a list with the IDs of products that are invalid.

To tell apart products that your user purchased from products that are simply available for purchase, you can call IsProductPurchased providing the ID of a product: 

if InAppPurchase1.IsProductPurchased(ProductID) then { Do something. }
Note: If the list of products contains a consumable product that has been purchased, now is the time to consume this product.

TProduct provides many properties that you can read to obtain information about each product.

Purchasing a Product

Before you allow your user to purchase products, call CanMakeInAppPurchases to check whether your user is allowed to make purchases (True) or not (False): 

if not InAppPurchase1.CanMakeInAppPurchases then { Disable or hide the in-app payments GUI elements of your application. }

To request the purchase of a product in the list of available products from your in-app payment service, call PurchaseProduct with the product ID: 

InAppPurchase1.PurchaseProduct(ProductID);

If there is an error, TInAppPurchase.OnError is triggered with Purchase as FailureKind.

If the purchase is successful, TInAppPurchase.OnPurchaseCompleted is triggered instead. This event provides the ID of the purchased product, and its NewTransaction parameter is True if the product has just been purchased or False if it has been restored. Use this event handler to manage purchased products; for example, if the purchased product is a consumable product, consume it.

Consuming a Product

Note: TInAppPurchase does not provide any method to find out whether a product is consumable or non-consumable. Your application must be able to tell them apart on its own. For example, you can hardcode a list of consumable or non-consumable product IDs in your application.

Consumable products are products that can be purchased more than once. When your user purchases a consumable product, you must call ConsumeProduct to inform your in-app payment service that this product has been consumed: 

InAppPurchase1.ConsumeProduct(ProductID);
Notes:
  • Alternatively, you can call ConsumeProducts with a list of product IDs.
  • iOS In-App Purchase does not require to be informed of consumed products.

After you call one of the methods to consume a product, one of the following events is eventually triggered:

  • TInAppPurchase.OnConsumeCompleted if the product is consumed successfully. Handle this event to process this purchase in your application. For example, if your application keeps a counter of cookies and your user buys a "5 cookies" product, you can increase the count of cookies in your application by 5.
  • TInAppPurchase.OnConsumeFailed if an error occurs that prevented the product from being consumed. The ErrorMessage argument of this event provides a detailed description of the error.

Restoring Products Purchased from a Different Device on the Current Device

In Google Play In-app Billing, the non-consumable products of a user always appear as purchased on any device of this user. You do not need to do anything to restore these purchases.

In iOS In-App Purchase, the non-consumable products of a user do not appear as purchased by default when your user switches to a different device. To restore products purchased from a different device on the current device, you must call RestorePurchasedProducts. Restoring a product, which is similar to purchasing this product for free, triggers TInAppPurchase.OnPurchaseCompleted with False as the value of the NewTransaction parameter. Handle this event to keep track of restored purchases.

Notes:
  • If your user attempts to buy a previously purchased product again, the purchase comes at no cost for your user.
  • Restoring purchases prompts for the user App Store credentials. You should not automatically restore purchases. Instead, you can let users start a restoring operation manually, for example with a "Restore" button.

Downloading Product Content Hosted on iTunes

When you define a product on iTunes for the iOS In-App Purchase service, you can upload content to iTunes and associate this content with your product, so that your application can download this content from iTunes.

When a user purchases or restores a previously purchased product, the TInAppPurchase component automatically starts downloading the downloadable content of the product. TInAppPurchase.OnDownloadProgress is triggered as the content is being downloaded, so that you can keep track of the progress and estimated remaining time of the download. Once the download finishes, TInAppPurchase.OnDownloadCompleted is triggered; this event provides the local path to the downloaded file so that you can open it.

Note: A product might have several downloadable files associated with it. Each downloadable file has its own ID, and OnDownloadCompleted provides both the ID of the product and the ID of the downloaded content.

The instances of TProduct that you obtain through the iOS In-App Purchase service when you query a list of products provide information related to the downloadable content of the product:

Your application should keep track of the version of a product downloadable content. When TProduct.DownloadContentVersion is not the same version as it was when you first downloaded the content from iTunes, you might want to download the content again to let your user have the latest version of the purchased content. To update any downloaded content, call TCustomInAppPurchase.RestorePurchasedProducts. The download events, OnDownloadProgress and OnDownloadCompleted, are triggered again as the latest content is downloaded.

Testing Your In-App Purchase Products

You can test your in-app purchase products without incurring charges using an iTunes Connect test user account. See Testing In-App Purchase Products.

See Also

Retrieved from "https://docwiki.embarcadero.com/RADStudio/Athens/e/index.php?title=Using_the_iOS_In-App_Purchase_Service&oldid=273426"