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()
withBillingClient.queryProductDetailsAsync()
- Replace
SkuDetailsParams
withQueryProductDetailsParams
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 ofSkuDetails
forBillingFlowParams
- 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
Top comments (0)