Understanding Google Play Billing Library v5.0

This year’s annual I/O conference brought us a new major version of the Google Play Billing Library. Google added new methods, deprecated and removed some older ones, but most importantly, they introduced a brand new subscription model that should change our ways of working with in-app purchases. Let’s get into more details and see what Google Play Billing Library 5.0 has to offer.

New subscription model: more flexibility, less complexity

The true highlight of the Google Play Billing Library 5.0 is the renewed subscription model. Google significantly reworked the subscription architecture by adding new entities – base plans and offers. Previously, offers (introductory offer and free trial) were directly tied to the subscription entity, which meant you had to create a new subscription every time you wanted to test a new offer, which wasn’t really convenient. New architecture solves this problem by detaching the offer into a separate entity. This can be very well seen in the illustration:

We can see that the subscription we’re accustomed to now has a more complex, yet more flexible structure. Subscription itself has become a separate core element that consists of base plans, which in their turn can include one or more offers. All the attributes that used to be included in one subscription are now shared within these three entities.

Subscription now only states what benefits the user gets and provides only basic information: identifier, title, description, and taxes info.

Base plan mainly provides information on the billing period and renewal type, which can be auto-renewing or prepaid. But it as well states the grace period and info on the prices and availability for different regions.

Offer acts as an entity that provides additional marketing attributes, like free trial and introductory prices. Here’s where the eligibility comes into play, as offers are available only to the users who meet the eligibility criteria that you personally define. For example, a base plan with a standard monthly subscription is available to anyone, but a monthly subscription offer with a 15% discount is available only to a certain eligible group of people, that you define yourself. Depending on the goal, offers can be divided into:

• Acquisition offers that are based on trials and discounted prices.
• Upgrade/crossgrade offers that help move users to higher tiers or longer billing periods.
• Custom offers where you define the parameters as you wish. Usually used for win-back campaigns, second chance free trials, etc.

Pricing itself gets more flexible as well, with a number of options you can set within an offer:

• Regional availability: specify countries, territories and pricing for each region. 
• Pricing updates: update the price of your subscription just for new subscribers, leaving the current ones unaffected to this. 
• Prepaid plans: price prepaid plans with top-ups, which is useful for countries and regions where pay-as-you-go is standard.

To sum it up, users now purchase a base plan or an offer to gain access to the subscription, instead of just purchasing a subscription. If it still sounds confusing, let’s have a look at the example:

For a standard three-product paywall you had to have three separate subscriptions, for example weekly, monthly, and annual. Let’s say the weekly subscription had just a standard price, the monthly one offered a free trial, and the annual option also offered the trial along with a discount. But imagine that you had a cohort of monthly subscribers that you wanted to upgrade to the annual subscription by offering a higher discount for a limited amount of time. In this case, you had to create a whole new annual subscription product with the desired parameters, because all the attributes belonged to the subscription entity.

If you transfer the same paywall to the new subscription model, you’ll have only one subscription entity split into three base plans: weekly, monthly, and annual. And then two of these plans will have additional offers: monthly plan will have a free trial offer, and the annual – offer with a free trial and a discount. So if you want to present the cohort of monthly users with a higher discount for the annual subscription, all you have to do is add another offer to the already existing base plan. It’s a really basic example, but it very well illustrates the working mechanism of the new model.

This approach should ease the developer’s headache of creating a new subscription entity each time they want to test a new offer, and make the testing process more flexible in general. 

Play Billing Library 5 in-app messaging 

In-app messaging is another interesting feature introduced by Google that’s supposed to help you retain your subscribers with the declined payment. With the help of the in-app messaging API, the users, whose payment gets declined, will see a message reminding them to update their payment info. According to Google, this approach showed 2x increase in user recovery, as well as growth in overall subscriber spend.

Google Play Billing Library 5.0 backward compatibility

As of now, Google Play Console is already working with the new version of the subscription model, which means that all of the old subscriptions have been automatically converted to the new format. But don’t worry, they’re still working, as Google made them backward compatible. You can still view them in your console but they’re displayed with the new structure (subscription, base plans, offers). However, they were made read-only, which means you shouldn’t edit them, if you want everything to work fine. But you can still edit them on condition that you will no longer be able to configure or update it through the InAppProducts API.

Before editing your subscriptions in the Console, Google recommends you to update your backend integration to use the new Subscription Publishing endpoints, such as: monetization.subscriptions, monetization.subscriptions.baseplans, and monetization.subscriptions.offers. You can read more about this and other technical aspects of the May update in the official documentation.

Remarkable technical updates

Several notable changes has been made in the Play Billing Library 5 in terms of code, so let’s highlight them:

• SkuDetails class has been deprecated. Instead, Google suggests using ProductDetails that contains information about the subscription, its base plans and offers. You can find more details about the migration here.

• launchPriceChangeFlow has also been deprecated and will be removed in the future. Here’s more information on how to do without it.
• Added BillingClient.queryProductDetailsAsync() to replace BillingClient.querySkuDetailsAsync().
• The queryPurchases method has been removed. 
• The setIsOfferPersonalized() method has been added. It’s required to show a personalized price for EU clients on the Google Billing purchase screen.

Is it important to upgrade ASAP?

While currently using the 4.0 version, we’re working towards implementing Google Play Billing Library 5.0 in our service. However, in our opinion, there’s no need to hurry in upgrading to the new version. All the subscriptions created with the previous version can still be easily accessed and function well in the backward-compatible mode. New subscriptions can also be created but they must include one base plan and one offer marked as backward-compatible. Other than that, we’re looking forward to switching to the new subscription model in the near future and providing you with more comfort and more room for experimenting.