Google Play Billing Library 1.0 released

Posted by Neto Marin, Developer Advocate

In June we announced the developer preview for a new Google Play Billing Library. Today, we are pleased to announce the official release of the Play Billing Library 1.0. This library simplifies the development process for Google Play Billing, allowing you to focus your efforts on your app.

Thank you for your valuable feedback and suggestions that helped us reach the 1.0 release. Watch the video below for a quick overview of the library's features.

Before you start

With Play Billing, you can receive payments from users around the world via a payment system they trust and you can take advantage of features and reports in the Play Console to manage and earn more revenue.

If you have never implemented in-app billing in your apps, or you want to know what you can offer using Play Billing Library, read the In-app Billing Overview to familiarize yourself with concepts and terminology that make it easier for you to implement In-app Billing using the Play Billing Library.

Getting started

Play Billing Library is available through Maven repository, and adding Play Billing Library to your project is simple as adding the following dependency into your app's build.gradle file:

dependencies {
    ...
    compile 'com.android.billingclient:billing:1.0'
}

The Play Billing Library 1.0 automatically adds the com.android.vending.BILLING permission to your APK. This means you no longer need to manually include it in your application module's manifest.

BillingClient and PurchasesUpdatedListener

These classes are the most important pieces when integrating the library into your Android app. The BillingClient is the bridge between your app and Google Play. You will use it for listing available products, starting the billing flow for in-app products or subscriptions (i.e. opening the payment interface), getting user purchases, and creating or modifying subscriptions.

When creating your BillingClient instance, you'll need to set a PurchasesUpdatedListener. This allows your app to receive updates from the In-app Billing API, including transaction results after the billing flow, as well as purchases completed outside of your app, e.g. user redeemed a Promo Code or bought a product on another device.

The following code demonstrates how you could override the onPurchasesUpdated() method of your PurchasesUpdatedListener:

@Override
void onPurchasesUpdated(@BillingResponse int responseCode,
        List<Purchase> purchases) {
    if (responseCode == BillingResponse.OK
            && purchases != null) {
        for (Purchase purchase : purchases) {
            handlePurchase(purchase);
        }
    } else if (responseCode == BillingResponse.USER_CANCELED) {
        // Handle an error caused by a user canceling the purchase flow.
    } else {
        // Handle any other error codes.
    }
}

You can implement the PurchasesUpdatedListener in your Activity or in any other class you want, according to your app's architecture. And here's the code for creating the BillingClient instance, and setting the PurchasesUpdatedListener:

mBillingClient = BillingClient.newBuilder(mContext)
                              .setListener(mPurchasesUpdatedListener)
                              .build();

Listing and selling products

To sell products in your app, first, you need to add them using the Play Console. For more details about how to add in-app products see the page Administering In-app Billing.

Attention: If this is a brand new app, before adding the products you must publish it to the alpha or beta distribution channel. For more information, see Draft Apps are No Longer Supported.

To get a list of product details with prices for current user, call querySkuDetailsAsync(). You must also specify a listener which implements the SkuDetailsResponseListener interface. You can then override the onSkuDetailsResponse() method which notifies the listener when the query finishes, as illustrated by the following sample code:

List<String> skuList = new ArrayList<> ();
skuList.add("premiumUpgrade");
skuList.add("gas");
SkuDetailsParams.Builder params = SkuDetailsParams.newBuilder();
params.setSkusList(skuList).setType(SkuType.INAPP);
mBillingClient.querySkuDetailsAsync(params.build(),
    new SkuDetailsResponseListener() {
        @Override
        public void onSkuDetailsResponse(SkuDetailsResult result) {
            // Process the result.
        }
    })

After the user chooses a product to buy, you'll need to start the billing flow and handle the transaction result. To start a purchase request from your app, call the launchBillingFlow() method on the Play Billing Library client. You must call the launchBillingFlow() method (and all the other methods from BillingClient) from the UI thread.

The launchBillingFlow() method needs BillingFlowParams object that contains relevant data for completing the purchase, such as the product ID of the item to purchase and the product type (in this case, SkuType.INAPP). To get an instance of BillingFlowParams, construct it with newBuilder() method:

BillingFlowParams.Builder builder = BillingFlowParams
                                       .newBuilder()
                                       .setSku(skuId).setType(SkuType.INAPP);
int responseCode = mBillingClient.launchBillingFlow(builder.build());

As we mentioned earlier, the transaction result will be sent to the onPurchasesUpdated() method. For details how to process the data received on onPurchasesUpdated() and how to handle a purchase, check the section Purchase an item in our training guide.

Consuming products

By default, all in-app products are managed. It means that Google Play tracks the product ownership and doesn't allow to buy multiple times. To be able to buy a product again, you must consume the product before it becomes available again.

It's common to implement consumption for in-app products which users may want to purchase multiple times, such as in-game currency or equipment. You typically don't want to implement consumption for in-app products that user purchases once and provide a permanent effect, such as a premium upgrade.

To consume a product, call the consumeAsync() method on the Play Billing Library client and pass in the purchaseToken String value returned when you made the purchase. The consumption result is returned via onConsumeResponse() method of the ConsumeResponseListener interface, that you must override to handle the consumption result.

The following example illustrates consuming a product using the associated purchaseToken:

ConsumeResponseListener listener = new ConsumeResponseListener() {
    @Override
    public void onConsumeResponse(@BillingResponse int responseCode, 
                                  String outToken) {
        if (responseCode == BillingResponse.OK) {
            // Handle the success of the consume operation.
            // For example, increase the number of player's coins,
            // that provide temporary benefits
        }
    }
};
mBillingClient.consumeAsync(purchaseToken, listener);

Sample updated: Trivial Drive V2

With a new library comes a refreshed sample! To help you to understand how to implement in-app billing in your app using the new Play Billing Library, we've rewritten the Trivial Drive sample from the ground up.

Since we released Trivial Drive back in 2013, many new features, devices, and platforms have been added to the Android ecosystem. To reflect this evolution, the Trivial Drive v2 sample now runs on Android TV and Android Wear.

What's next?

Before integrating within your app, you can try the Play Billing Library with the codelab published during Google I/O 2017: Buy and Subscribe: Monetize your app on Google Play.

In this codelab, you will start with a simplified version of Trivial Drive V2 that lets users to "drive" and then you will add in-app billing to it. You'll learn how to integrate purchases and subscriptions as well as the best practices for developing reliable apps that handle purchases.

Get more info on the Play Billing Library and the official reference for classes and methods documentation on the Android Developers website. For a step-by-step guide to implementing the Play Billing Library in your project, visit the library's training class.

For more details about the Play Billing Library 1.0 release, check out the Releases Notes page, where you can find updates, bug fixes and behavior changes on the library since the Developer Preview release.

We still want your feedback

If you have issues or questions, file a bug report on the Google Issue Tracker, and for issues and suggestions on the sample (like a bug or a new feature), contact us on the Trivial Drive issues page.

For technical questions on implementation, library usage, and best practices, you can use the tags google-play and play-billing-library on StackOverflow or visit the communities on our Google+ page.