[MUSIC PLAYING]
DIANA GARCIA RIOS: Hi, my name is Diana.
And I'm a Developer Relations Engineering Manager here
at Google.
Today, I'm excited to talk to you about the new version
of the Play Billing system, and how
to migrate to the Play Billing Library, version 5.
So in today's talk, first we're going
to introduce the new capabilities built
into the system, especially for subscriptions.
And then we're going to check what changes your integration
may need to adopt these new capabilities.
So let's talk about this new set of capabilities.
The first thing you need to know is
that the new version was built completely backwards
compatible.
So your app, your backend integration,
and your current subscriptions work exactly as before.
You can adopt the new capabilities gradually.
So once you adopt Play Billing Library
5 and the new backend endpoints, you're
ready to add them to your integration little by little.
And we have introduced new ways to sell and manage
your subscriptions, reducing the operational costs that
is associated with the need to create and manage
an ever-increasing list of skills.
So for the new features, we have new ways
of selling subscription plans, like prepaid plans.
And with price change management and pricing cohorts,
you're in control of when your existing subscribers get
a new price, when you need to update
your subscription products' pricing.
There's new offering capabilities,
for example, pricing phases, for easier, more flexible offer
definition, and also, easier offer eligibility control.
There's another interesting addition
with base plan and offer deactivation, which
allows you to activate or deactivate
with subscription products that are available for purchase
in your app.
That, along with tags, gives you a flexible way
of managing your subscriptions catalog
without having to do many code changes when you change what's
available for purchase.
If you want to see more about the new subscription
configuration capabilities, you can read the "Create and manage
subscriptions" article on the Play Help Center.
So subscription product, Google Play Billing,
are now represented by a hierarchy of new entities
that relate with different aspects of the user's
relationship to the subscription product.
So subscriptions represent what you're selling to the user--
the product, the benefits, and the subscription.
Base plans are how you're selling it to the user.
So it talks about whether, if it's an autorenewable plan,
or a prepaid plan, the billing period length, and also
the base price.
And offers are pricing modifications
that you can apply on top of the base price,
so for example, free trials or introductory prices.
Developers can also establish their offer eligibility
criteria.
We have introduced new classes, both in the Play Billing
Library and the Google Play Developer API,
to manage these new entities.
Your pre-existing subscriptions before the launch
were automatically converted to these new entities.
But what happened with them?
Don't worry.
Any existing subscriptions work exactly as before
and are now represented by one subscription object,
with one backwards compatible base plan,
and if you had Enterprise free trial, one
backwards compatible offer.
There can only be one combination of backwards
compatible based on an offer in each subscription.
This ensures that the system knows
how to translate back to the older entities used
by live versions of your app.
And your converted subscriptions were made read-only
in the conversion process.
This is just to avoid any accidental changes
after the switch.
And you can make them editable again from the Play Console.
If you do that, mind, if you make any changes,
that you're not affecting your live versions of your app
in any way that can break them.
It might be simpler to create new subscription
for the new versions of your app that we're
going to build with Play Billing Library 5.
And to read more about how to configure your subscriptions
catalog for this new system, you can
read the documentation that is referenced there at the bottom.
OK, so now that we have seen the new features that we released
and the state of your subscriptions catalog right
after the conversion, we will discuss how to gradually move
to the new model.
Google Play Billing Integrations talk
to the Play backend via the Play Billing Library
from the Android app, and the Google Play Developer
API from the Developer backend.
This Developer backend component is
essential to manage the subscription entitlements
correctly and efficiently.
For this migration, you're going to have
to modify probably both.
While you don't need to migrate immediately
for your integration to work as it used to work before May,
we recommend developers try to stay in the newest version
possible.
Each Play Billing Library version
has a lifespan of two years from the moment it gets released.
This year, we deprecated Play Billing Library 3.
Migrating your app from Play Billing Library 3
to Play Billing Library 5, it's very similar
to start from Play Billing Library 4.
It also gives you the additional benefits
of the new capabilities, and a little extra time
before your next required migration.
So I'm going to mention the Google Play Developer
API several times in this talk.
In particular, I will be referring
to the component of it called the Subscriptions
and in-app purchases API, built to manage
in-app purchases from your app.
OK, so the new backend API includes a new set of endpoints
to manage your subscription's catalog programmatically, all
of them under monetization.subscriptions.
It also includes a new pricing conversion endpoint that
allows you to translate any price to all the
supported regions and currencies on Google Play.
And there's a new endpoint as well,
to manage your subscription purchase status.
Developers may handle their product catalog
programmatically, in addition, or instead of,
using the Play Console.
If you do this, you're going to want to look at these changes
because the moment you make your subscriptions
editable on Play Console, the old endpoint
won't work for them.
So if you now use inappproducts for managing your subscriptions
catalog, you should start using monetization subscriptions.
The new endpoint uses create instead of insert, patch
for updates, and introduces the capability
to archive a subscription.
The inappproducts endpoint is still there, and still works
for one-time purchase products.
And you could also use it while your existing subscriptions
that were converted are not made editable
for your subscriptions.
So the new resources adopt the same hierarchical structure
that we talked about with the entity.
So we have subscriptions with several base plans,
and potentially several others under them.
To see how these new resources map to the old inappproduct
resource, please check the Compatibility Guide
on the documentation, under the title, May 2022
Subscription Changes Guide.
So now that you have learned how to configure your subscriptions
catalog in the new model, let's see
how to change your app to sell these new products.
We are going to follow the steps in the Google Play Billing
Library 4 to 5 Migration Guide, which
is in the Android developer documentation site.
The first step is upgrading the dependency of your app
to the Play Billing Library to the latest version.
You do this on your build.gradle file.
The latest version is 5.1 right now.
If you started your migration from Play Billing Library 4,
your app will probably build right away.
If you started with 3, some methods
may have been deprecated since then.
To check out what methods were deprecated in each version,
you can look at the Release Notes page.
So the first step now is the initialization
of the BillingClient.
And it has not changed since the previous version.
You will still call new builder to create the client.
And you will set a listener to purchases of the listener.
These will be called every time there's
new purchases in your app.
After you initialize the BillingClient,
you will establish a connection with Google Play,
just like you did before.
This is the same startConnection call.
And you will implement a couple of callbacks,
onBillingSetupFinished, for successful connections,
and onBillingServiceDisconnected,
to let you know when the BillingClient has
lost the connection.
It's really important that the connection
is in a healthy state before you enter any user-critical flows.
So now that the connection is established,
it's time to get the products available for purchase
from Google Play.
There are changes in this step so your app can
support the new product types.
So queries key details, I think, is a deprecated method
in Play Billing Library 5.
It's still present for backwards compatible reasons.
But you're going to have to switch this call.
We have created new classes to replace the SkuDetailsParams
and SkuDetails as well.
So now you will use queryProduct's async.
And to build the parameters for this one,
you will provide a list of queryProductDetailsParams.
Each of these contains the product ID
of the product you are trying to retrieve and the product type.
These are all new classes.
Once you go QueryProductDetailsAsync,
the callback will return a list of ProductDetails.
Each ProductDetails item contains information
about the product, so its description, the ID, the title,
the type, and so on.
An important difference with this new system
is that each product, in particular, subscription
product, contains a list of SubscriptionOfferDetails.
This object contains all the different ways
a user can acquire this product.
If the user is not eligible for a particular offer,
it won't be returned at this step.
So that's how the system handles predefined eligibility.
So for example, if a base plan doesn't have any special offers
under it, or the user is not eligible to any
of the special offers in their base plan,
you will only get one element in this list.
It's one offer with only one pricing phase contained
in the base price.
The Subscriptions Offers Detail Object contains some details
about the offers that will help you
decide how and when to display it, and how to sell it.
So for example, getOfferToken returns the offer token
needed to launch the purchase of the specific offer.
And the pricing phases will return the different prices
that the user will get along their subscription journey.
So you can correctly display the product.
All right, so developers can decide
which offers will be surfaced in the app, and how.
offerTags, in particular, offers you
a new tool to categorize your offers
and decide how this happens.
In this example, you can see the developer has created
a tag called loyalty1year.
And he uses it to decide which offers should
be displayed to a user that qualifies for a special loyalty
program.
So if the user meets their developer criteria
and the offer is available to them,
the app is able to display it.
The nice thing about using offerTags for this
is that if the developer wants to change
what offer the users in this program apply to,
they only have to move that label to a different offer.
And the app will continue working exactly
as before with the new offer, without having
to change the code.
So it makes it a little bit more manageable.
All right, so let's say the user already selected
which offer they want to buy.
It's time to launch the billing flow.
OK, the BillingFlowParams setSkuDetails method
has been deprecated.
Let's see how to specify the product
the user wants to acquire.
So for each product that will be bought,
create a ProductDetailsParams object
that contains the product details object that we talked
about before, and the offer token
that indicates the exact offer you're going to sell the user.
This is a string value.
And that billingFlowParams goes into the--
so that list of ProductDetailsParams
goes into the billingFlowParams.
And it's used with the method, launchBillingFlow.
Just as before, you also specify a reference
to an activity from which the BillingFlow will be launched.
And so after the user goes through the BillingFlow,
it's time to handle the outcome.
This step is very similar as before.
The only small change is on how you pull new active purchases.
So since this queue time is deprecated,
you will call queryPurchasesAsync now,
with a queryPurchasesParams object.
And in this object, you have now a set product type method
to take this equivalent step to indicate
what kinds of purchases you're pulling.
There's a new enum product type that
lets you indicate whether they are service or enum products.
And these are the main changes in your Play Billing Library 5
integration.
After making these changes, your app
is ready to leverage the new features in the Google Play
Subscriptions platform.
All right, so once your app is migrated,
your backend needs to start handling purchases made
with these new methods.
The subscription status management component
in your backend uses the Subscription Purchases API.
Let's see how to change this component
to handle these new types of purchases.
All right, with real time developer notifications,
developers get a message every time a purchase state changes.
And with that information, they're
able to call the Google Play Developer
API to pull the purchase status, and adjust
the entitlement accordingly.
This remains the same.
The difference in this new version
is that the endpoint you're going
to use to pull that subscription status is a different one.
It's called purchases.subscriptionsv2.
And it only has one method, get.
This new get method returns any set of resources
with the purchase status.
The all endpoint purchases subscription is still there.
And all the other developer lifecycle
management actions, such as acknowledging a subscription
or canceling it, are still in the old endpoint.
So you will still use it.
The old get function in that old endpoint
only works for purchases made with all methods of the Play
Billing Library.
So it's not going to be valid if you're already
selling new types of subscriptions in your app.
And this is the new entities.
The SubscriptionPurchasedV2 one contains
information about the line items or the different products
acquired in this purchase.
Each of them is a SubscriptionPurchaseLineItem.
And you can see how you can obtain things like the base
plan that the user acquired, or the offered details.
To see more about how these entities map to the old one,
you can check our May 2022 New Subscription Features Guide
on the developer documentation.
All right, so this is an example, Jason,
of what you would obtain after calling the Subscription
Purchases Status API.
And so you can see, pretty simple.
So thank you for your attention today.
I hope this presentation helps you
plan your migration to the new version of the Play Billing
Library.
For more information, always check out
our developer documentation.
[APPLAUSE]
[MUSIC PLAYING]