Using the Google Play In-app Billing Service

From RAD Studio
Jump to: navigation, search

Go Up to Creating an Android App


In-app payment services let you sell digital content directly within your applications. Google Play In-app Billing is the Google in-app payment service for Android. This topic describes how to give your applications access to Google Play In-app Billing using FireMonkey.

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

Supported Devices

FireMonkey supports Google Play In-app Billing on devices running Android 2.2 or later and the latest version of the Google Play store. See also FireMonkey Platform Prerequisites, Android Requirements.

Note: Android emulators are not supported.

Prerequisites

Before you can use the Google Play In-app Billing service, you must:

Configuring Your Application for In-app Billing in Google Play

Google requires you to have a draft application uploaded before you can add in-app products.

Before you start adding Google Play In-app Billing support to your application, upload your application in its current state to Google Play:

  1. Prepare your application for deployment.
  2. Create a signed .apk package for your application.
  3. Upload your new application to Google Play.

On the page of your application, on the Google Play Developer Console, click Services and APIs. The Services and APIs page shows the license key of your application. When you configure your instance of TInAppPurchase to connect to Google Play, you must copy this license key into the ApplicationLicenseKey property.

TInAppPurchase supports Managed In-app Products. See In-app Billing Version 3, Product Types for more information about Managed products.

Note: Subscriptions are not currently supported.

Adding Google Play In-app Billing Support to Your Mobile Apps

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

Establishing a Connection to the Google Play In-app Billing Service

Before you can use the Google Play In-app Billing service, you must configure TInAppPurchase to connect to the Google Play In-app Billing service and establish a connection.

Configuring the Connection Data for the Google Play In-app Billing Service

To connect to the Google Play In-app Billing service on Android, you must copy your license key into the ApplicationLicenseKey property of TInAppPurchase. You obtain a license key after configuring your application for In-app Billing in Google Play; for example: 

InAppPurchase1.ApplicationLicenseKey := 'MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgEAlGKUp9KCAQjzJdrjDaCC2Z2P0K751w1KAL3cBLhDqRSYDnug+nZKzeg2+R3KOIDVpJU7+PXz8jyf07m/30Y0J1CmOBf6NK/MIsXq3BmWb4/UIUW1aKzlHiiVtpcm26n3hOSmnnfkhasbfQo75puBBTbURvumOFfwUAJ2BM9FzAOPWzsAqT1brYI8iu+NHDT+gGQl7uOTgEN3jbBD/la5qAt' + 
'evOGbgP1DhfKtsi91+/oyy3+lphWNn2A+RE1KOx4lnHp0wZyOEvDP/CPZneT0YYgqG6MtawM+Mij/75XwhJEdeOSXYya7BN6hg49JX2WJxCRc7JqbgzN9vsRn6hSceQ5MuQIDAQAB';
Note: Due to a Delphi compiler limitation, String literals cannot exceed 255 characters. The solution is to split the string into several parts, as seen above.

Connecting to the Google Play In-app Billing Service

To connect to the Google Play In-app Billing 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 the Google Play In-app Billing Service

Once you have established a connection to the Google Play In-app Billing 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 the Google Play In-app Billing 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 the Google Play In-app Billing service that this product has been consumed: 

InAppPurchase1.ConsumeProduct(ProductID);
Note: Alternatively, you can call ConsumeProducts with a list of product IDs.

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

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.

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.

Using a Developer Payload String to Verify Purchases

When you use the Google Play In-app Billing service, you may give the TInAppPurchase.TransactionPayload property a value, a code of some kind, that is unique to the user of your application. This value is sent to the Google Play In-app Billing service when your user purchases a product from your application.

During the purchase, the Google Play In-app Billing service sends you back a developer payload string that should match the string that you previously defined in the TransactionPayload property. To check that both strings match and thus verify that the purchase was indeed ordered by your user, handle the OnVerifyPayload event: 

procedure TForm1.InAppPurchase1VerifyPayload(Sender: TObject; const Payload: string; var PayloadOk: Boolean);
begin
  if Payload.Compare(FPayload) <> 0 then
    PayloadOk := False;
end;

If the handler of this event sets PayloadOk to False, the purchase is invalidated.

Warning: The same user may use your application on different devices. The developer payload string must be the same across different devices for the same user. For example, it cannot be a random string generated by your application, as this string would not be the same on all devices.

Testing Your In-App Purchase Products

You can test your in-app purchase products without incurring charges using test users. See Testing In-app Billing.

See Also

Retrieved from "http://docwiki.embarcadero.com/RADStudio/Sydney/e/index.php?title=Using_the_Google_Play_In-app_Billing_Service&oldid=250031"