Migrating to Google Play Billing Library 5

At Google I/O 2022, the Google Play Team presented Google Play Billing Library 5.0 – the newest version of its in-app billing and subscriptions library.

In this post, we'll go through some of the main steps you need to take to migrate your Android app from Google Play Billing Library 4 to PBL5.

This is an excerpt of a post first published on the RevenueCat blog, where you'll find more information on Google Play Billing Library 5

Also, the cover image is what DALL·E makes of the prompt "A cat hugging the Google Play logo" 😅

Highlights of a Google Play Billing Library 4 to 5 migration

If you’re not using RevenueCat for Android in-app subscriptions, migrating from PBL4 to 5 involves multiple steps. We’ll share the highlights and most important changes you’ll need to make here, but you’ll find more details in Google’s integration guide, and billing specific samples on GitHub.

Creating a product catalog

Google recommends creating new products using the updated entity structure of Google Play Billing Library 5 before migrating your app. You can do this by consolidating the duplicate products that represent the same subscription benefits with different configurations of price, duration, etc.
This is the recommended first step as editing converted subscription products can result in issues with older versions of your app that still use PBL4 and deprecated methods like querySkuDetailsAsync().

Managing your catalog with the new API

If you manage your subscriptions automatically with the Developer API, there are three new endpoints to be aware of:

• Monetization.subscriptions to manage subscription products
• Monetization.subscrtipions.basePlans to manage base plans for your subscriptions
• Monetization.subscrtipions.basePlans.offers to manage the offers associated with your base plans

For anything but one-time purchases, these new endpoints should be used via the Subscription Publishing API. Your one-time purchases will still be managed via the inappproducts API previously used for subscriptions as well.

Updating the Billing Library dependency

Created your new products? You can now migrate your app by updating your Play Billing Library dependency in your build.gradle file:

dependencies {
    def billingVersion = "5.1.0"

    implementation "com.android.billingclient:billing:$billingVersion"
}

Note that on October 31st of 2022, Google released the Google Play Billing Library 5.1, which – if you’re implementing PBL5 now – should be the version you’re using.

Showing available products

Because we’ve switched from SKUs to Products, the calls required to show eligible offers have changed:

• Replace BillingClient.querySkyDetailsAsync() with BillingClient.queryProductDetailsAsync()
• Replace SkuDetailsParams with QueryProductDetailsParams

Query results have gone from SkuDetails to ProductDetails, showing you information about the product (title, type, ID, etc), similar to before. New is List<ProductDetails.SubscriptionOfferDetails>, which contains the available offers for a specific user. Note that – unlike in PBL4 – you’ll be able to see several different offers for the same subscription period. In some cases, Google will handle eligibility, but in other cases, you’re able to define which offers show up in the paywall.

Important: If you’re showing a personalized offer as determined by Art. 6 (1) (ea) CRD of the Consumer Rights Directive (2011/83/EU) to a user in the EU, you’re required to disclose this via the Play UI. To do this, customize setIsOfferPersonalized() with true or false, depending on the offers shown to your user.

Launching the purchase flow

There are very few changes here, beyond going from SKUs to offers:

• Use ProductDetailsParams instead of SkuDetails for BillingFlowParams
• Use SubscriptionOfferDetails to get offer ID, base plan ID and other offer details

You’ll then pass the offerToken for a selected offer into the ProductDetailsParams object to purchase a product.

Processing purchases

This also largely remains the same, but you will need to pass a QueryPurchasesParams object with a BillingClient.ProductType value, instead of a BillingClient.SkuType value to queryPurchasesAsync().

Managing subscription status via the API

Your current subscription purchase status management backend component will be able to manage converted subscriptions pre-dating May 2022 as well as backward compatible offers, but will not support any of the new functionality introduced in Google Play Billing Library 5. To fully support the new subscription features, implement the new Subscription Purchases API (link), which will check purchase status and manage entitlements in your backend.

Replace calls to purchases.subscriptions.get with purchases.subscriptionsv2.get to access a new resource called SubscriptionPurchaseV2. There, you’ll find the necessary information to manage entitlements for subscriptions created in the new model.

Testing Android subscriptions for Google Play Billing Library 5

Before launching your app or submitting your app’s update, – as always – thoroughly test your subscriptions. The process to do so doesn’t differ from how you did it in PBL4, so simply follow the steps detailed in RevenueCat's ultimate guide to Android subscription testing.

Migrating to Billing Library 5, from Android Dev Summit ‘22

At this year’s Android Dev Summit, Diana García Ríos from Google’s Android team presented on the topic of PBL5 migrations. In this 16 minute video, she explains how to adopt Android and server integrations to take advantage of these new capabilities, and cust maintenance load by designing your subscription system for PBL5 from the bottom up:

Want to save yourself some pain?

RevenueCat was built to help developers manage the complexity of offering subscriptions across their mobile applications and web. Read more on our support for Android in-app subscriptions here, or sign up and start building