GlobalCharge Android Billing Library

This document is intended to provide an overview of the Globalcharge Android in-app billing Library (GAL) and ways in which it may be integrated to a developer's Android application.

See:
          Description

Packages
com.globalcharge.android  

 

This document is intended to provide an overview of the Globalcharge Android in-app billing Library (GAL) and ways in which it may be integrated to a developer's Android application. The GAL is a self-contained Java Archive (JAR) file that can be included in the classpath of your Android application. The GAL allows Android application developers to charge mobile users through their mobile phone accounts. The GAL was designed to minimise the integration process as well as the billing data held by the developer while not compromising the library’s seamless user experience.

Subscription and One-off Payments

GAL supports one-off payments as well as subscription payments. As the names imply, for one-off payments, the GAL will bill the user for a particular product in one transaction and communicate back to the developer's app and/or server web-service with billing confirmations. The subscription payment requires the user to enter a contract authorising recurring payments by making the first transaction. All subsequent transactions will be scheduled and billed at the subscription interval by the GlobalCharge Billing System. Billing notifications for recurring subscription transactions are delivered only to the developer’s server via a web-service.

There are two types of subscription payments:-

  1. GlobalCharge managed subscription payment
  2. Client managed subscription payments

For GlobalCharge managed subscriptions, the integration is as simple as one-off payment integration and exactly follows the same steps; the GlobalCharge subscriptions engine subscribes users and triggers the recurring subscription transactions at the subscribed payment intervals.

The Client-managed subscriptions type allow the client to retain scheduling control of subscriptions within their subscriptions engine and notifies GlobalCharge’s billing system when to bill the user. This type of subscription requires a custom integration with the developer's existing subscription engine. However, developers still have to integrate to the GAL as normal.

Integration

To fully integrate with the GlobalCharge Billing System for one-off payments, the client first needs to integrate on the Client-side by including the GAL in the Android application’s classpath. Secondly, there is a Server-side integration that involves implementing our server-to-server notification API to receive billing status notifications.

This document just focuses on the client-side integration for both subscription and one-off payments. The client-side integration is a four step process:-

  1. Include the GAL.jar file on your Android project's class path
  2. Provide a Payment activity (if you don't have one already) and implement all the callback methods of this Interface com.globalcharge.android.PaymentListener (see the sample Eclipse Project named GC_Sample)
  3. Add few permission elements and some generic attributes to the AndroidManifest.xml file of your application.
  4. Use the com.globalcharge.android.BillingManger to initiate the transaction (see the sample Eclipse Project named GC_Sample)

Products and Account setup

For each new Android application that requires a new GAL integration, we will setup a new account on the GlobalCharge Billing System, which will provide you with a unique Account ID (accountId) to identify that particular Android application. GlobalCharge will also setup and manage a seperate list of products for each country on your account. Products represent the virtual goods that your application or game is selling. So attributes of a product include Product Name (productName), Price (price), Currency (currency), Units (units) - i.e 30 credits, 3 Months subscrption) - etc. The GAL was designed to hide away this product management complexity from the devloper. This requires a one-time server-side setup

Displaying the Product Selection Screen

ONE STEP BILLING

The GAL can display the appropriate product selection screens (price selection screen) for each country, take selection from users, and display confirmation and notification screens whilst handling regulatory requirements, internationalisation, etc. With this approach, the client needs only to initiate payment by passing the accountId only once and finally, the GlobalCharge Billing System will notify the application and/or the server web-service the outcome of the billing transaction. GlobalCharge's terminology for this kind of setup is 'ONE STEP BILLING'.

TWO STEP BILLING

However, if there is a requirement to display the product selection screens within the client application, outside of the GAL, a flag can be set to indicate this to the GAL, which will then silently return the list of products available for the user's country on your account and not display the price selection screen. The client application will therefore take the price selection from the user and pass the selected product back to the GAL. GlobalCharge's terminology for this kind of setup is called 'TWO STEP BILLING'. It is two steps because first the application must initiate the payment, then the GAL accepts that and returns a list of products to the client application. Once the client application takes the product selection from the user, it calls the GAL again to request billing for the purchase of the selected product.

Testing the Integration

After you have completed the Integration, you can start testing your integration using our testing environments. GAL supports three types of Environment MODEs:-
  1. com.globalcharge.android.BillingManger.Environment.LOCAL
  2. com.globalcharge.android.BillingManger.Environment.TEST
  3. com.globalcharge.android.BillingManger.Enviroment.PRODUCTION

  1. Environment.LOCAL allows developers to test the integration without connecting to GlobalCharge's billing servers. It retrieves products and account configuration information from a sandbox server embedded into the GlobalCharge Android Library (GAL). This is the first stage of integration.
  2. Environment.TEST allows developers to test the integration with GlobalCharges Test server which is a clone of the Production server. To test the integration on the Test Platform, the developer will need a unique account and products setup. This is the second stage of integration.
  3. Enviroment.PRODUCTION allows developers to connect to the production platform. This is the default behaviour if the Environment MODE is not set. Similarly, when using this mode the developer will need prior Account and Product setup for the application. This is the final stage of integration before going live.