Understanding Google Play Billing Library v5.0- Android
Recently, in this year’s I/O (2022) the Google play team announced big changes made in the Google Play Billing Library v5.0.
Having to migrate to the new version myself, I gathered, while trying to structure my app around the new subscriptions model that some of these changes are still a bit confusing to many developers. Therefore, in this blog, I am going to explain why the changes were made, how to migrate to imbibe these changes and what is to be gained from it from monetization point of view.
What lead to the idea of restructuring the subscription model?
Digital subscriptions are the fastest growing methods for app monetization on Google Play. As the Google Play Billing Library evolved over the years, the Google Play team, in order to meet the developer demands to make the subscriptions less complex, have released an entirely new subscription model in May 2022.
In order to make managing a long list of subscriptions easy and scalable, the library has been redefined entirely in the form of subscriptions, base plans, offers, and pricing phases. All these changes let us provide more options to our users with a less complex hierarchical model.
Note- Even if the new subscription model is implemented and we may be seeing a new Play Console UI, the important thing to consider is that our existing plans, subscriptions, in-app products are now made backward compatible and will continue to function as is, with the old, deprecated SKU APIs. The documentation states that there is no urgent need to adopt the new changes right away and that we can migrate to these gradually.
Even if we do migrate the in-app billing library to v5.0, we can use the new APIs to query for these backwards compatible subscription items, where our already present subscription is converted to a base plan with a free trial automatically.
Understanding the new subscription model
With the new changes, we can now have a single subscription with one base plan and multiple offers underneath each base plan. These offers, each in turn have their own eligibility and pricing phases.
In this section I will cover the various subscription objects.
Subscription
A subscription is a single plan which defines a single set of benefits a user can avail. Example- Basic version or a Premium version.
A subscription represents different benefits that the users can gain access to like- photo editing options in a photo editor app or a set of features the users can use for a gaming app or certain free storage space in a DMS app, etc.
Base Plan
A base plan holds the base or actual price of a subscription. It also holds the billing period of a subscription and it’s renewal type. A subscription can have multiple base plans, each with a unique billing period.
- Example — For a Basic type of subscription entity a base plan can be- Basic Monthly, Basic Annual or Basic Prepaid plan.
- A billing period is of two types- Monthly and Yearly
- A renewal type is of two types- Auto-renewing and Prepaid.
— An auto-renewing plan entitles the user for subscription acquisition for a specific period with ability to extend the plan for the period at the end of each cycle.
— A prepaid plan entitles the user for subscription acquisition for a specific period without the ability to extend the plan. We can, however, opt (from the play console) to let the users buy the prepaid plan again. Users can also top-up the prepaid plans (just like mobile recharge top-ups) that can extend the plan’s end date.
— Users can switch between prepaid and auto-renewing plans either through the app or the play store. - Tags — A tag is a special, optional meta-data you can associate with your base plan and offers. They are super useful when you need to identify offers and base plans to show the most useful plans to the users. In fact, I personally found them to be the only source to plan my app’s offerings to the users.
— A tag can be up to 20 characters long, a base plan can have up to 20 tags associated with it, and it supports lower case letters (a-z), numbers(0–9) and hypen(-).
— For example- I can have tagsbasic-monthlyandpremium-monthlyto identify a monthly basic and premium plans and tagsbasic-yearlyandpremium-yearlyto identify yearly basic and premium plans. I can then, use these tags to show my monthly and yearly offerings in separate sections of my subscription offerings screen.
Offer
A base plan can hold multiple offers.
An offer is a special discount made available only to the eligible users. These eligible users can purchase a subscription at a special price set with this offer.
- Example — free trial, introductory price of 25% discount on the base plan price, etc.
- Note — Offers can be created only for the auto-renewing base plans.
Each offer under a base plan can be used to support a subscription’s lifecycle like- free trial to acquire new customers, provide upgrades between subscriptions or between renewal periods, or winback old customers by offering special discounts to them.
- When a user queries for the available subscriptions, they are shown only those offers that they are eligible to avail. For example, if a user has already used a free trial offer, the API does not return that offer in the list of eligible offers
The user can purchase a subscription in 2 ways- Either by purchasing a base plan or by purchasing any of the eligible offers from the app or from the play store
- Offer eligibility — We can define offer eligibility to provide various offers to the users based on their subscription status. Eligibility types (criteria) are-
— New customer acquisition is used to provide offers to first-time users (first time with this subscription or first time to all subscriptions in the app). For example- free trials or introductory discounts.
— Upgrade is used to let current users already subscribed to some subscription in your app with some introductory price to upgrade to a larger billing period or a premium subscription base plan.
— Developer determined lets us decide when we want our users to have certain offers. For example- we can have a 25% discount for the users who have not renewed their subscription due to some reason.
Developer determined offers’ logic and data resides within the app itself, hence these offers are available only in the app and not in the play store.
- Offer Phases/Pricing Phases — Each offer can have multiple pricing phases, which introduces offer prices in stages. For example- Your offer can have a free trial, followed by an introductory price, and then followed by the base plan price.
Pricing phases are especially handy when you want your users to fully understand the value your app has to offer before they are asked to pay for it.
— Pricing phases can have prices same as the base plan or less then that.
— Pricing phase can be an absolute amount, fixed discount, or percentage discount on top of the base plan. For example- $10, fixed $10 off on the base price, or 50% discount on the base price.
— The duration for each pricing phase is fixed.
— Payments for the phases can be single time or multiple. If multiple, we need to provide the number of recurring cycles.
- Offer Tags — Offers tags work similar to the base plan tags. They are used to determine which offer to show to the user.
In this section I explained, with examples, the basic subscription structure which was introduced with the new Google Play Billing Library v5.0.
Reference links for the same-
1. Understanding subscriptions — Play Console Help
2. https://developer.android.com/google/play/billing
3. https://android-developers.googleblog.com/2022/05/new-ways-to-sell-subscriptions-on-google-play_0530335598.html
Handling subscription migrations
The new subscription structure offers more scalability, where we can create appealing offers to existing users to upgrade from one plan to another.
Now that we have seen how to structure base plans and offers for our apps, let us quickly go through how to structure offers and base plans that allow users to migrate from one base plan to another or from one offer to another.
Example — Many of your users are regular subscribers of your basic monthly plan, we can create a curated offer for them, which upgrades them to the yearly plan with 20% discount for the first year.
This has two effects- the user is benefited with 20% of the total amount they would be paying for the year on monthly basis and we would be ensuring a regular subscriber for 1 year.
The structure of your subscription tree would be something like this-
Similarly, we can have offers that upgrades a prepaid user to monthly or yearly plan or those that upgrade a basic subscription type to premium subscription type.
Conclusion
There is plenty of documentation around the topic and the migration guide is itself very verbose, along with the in-app purchases google sample. However, while working on it, I found it rather difficult to grasp the concept. Therefore, we saw, in this blog, the new structure, how it affects our existing apps, how to build/scale your app around the new model, and how it would help us monetize better with less complexity.
