Google Play Billing Library release notes

This topic contains release notes for the Google Play Billing library.

Google Play Billing Library 2.2.1 Release (2020-05-20)

Version 2.2.1 of the Google Play Billing library is now available.

Bug fixes

Updated the default version of the Java Play Billing library that the Kotlin extension depends on.

Google Play Billing Library 2.2.0 release and Unity support (2020-03-23)

Version 2.2.0 of the Google Play Billing provides functionality that helps
developers ensure purchases are attributed to the correct user. These changes
replace the need to build custom solutions based on developer payload. As
part of this update, the developer payload functionality has been deprecated
and will be removed in a future release. For more information, including
recommended alternatives, see
Developer payload.

Google Play Billing Billing Library 2 for Unity

In addition to the current Java and Kotlin versions of Google Play Billing
Library 2, we released a version of the library for use with Unity. Game
developers using the Unity in-app purchase API can upgrade now to take
advantage of all Google Play Billing Library 2 features and to make the
subsequent upgrades to future versions of the Google Play Billing Library
easier.

Version 2.1.0 of the Google Play Billing library and the new Kotlin extension
are now available. The Play Billing Library Kotlin extension provides idiomatic
API alternatives for Kotlin consumption, featuring better null-safety and
coroutines. For code examples, see
Use the Google Play Billing Library.

This version contains the following changes.

Summary of changes

In BillingFlowParams,
deprecated setOldSku(String oldSku) and replaced with
setOldSku(String oldSku, String purchaseToken), to disambiguate when
multiple accounts on the device own the same sku.

Google Play Billing Library 2.0.3 Release (2019-08-05)

Version 2.0.3 of the Google Play Billing library is now available.

Bug fixes

Fixed a bug where querySkuDetailsAsync() would occasionally fail with code
DEVELOPER_ERROR instead of returning a successful result.

Google Play Billing Library 2.0.2 Release (2019-07-08)

Version 2.0.2 of the Google Play Billing library is now available. This release
contains updates to the reference documentation and does not change library
functionality.

Google Play Billing Library 2.0.1 Release (2019-06-06)

Version 2.0.1 of the Google Play Billing library is now available. This version
contains the following changes.

Bug fixes

Fixed a bug where debug messages were being returned as null in some cases.

Fixed a potential memory leak issue.

Google Play Billing Library 2.0 Release (2019-05-07)

Version 2.0 of the Google Play Billing library is now available. This version
contains the following changes.

Purchases must be acknowledged within three days

Note: This section describes a new requirement for acknowledging all purchases.
If you are already consuming purchases via consumeAsync(), you do not need
to make any further changes if you consume purchases within 3 days, as
consumeAsync() automatically acknowledges a purchase. Failure to properly
acknowledge purchases will result in purchases being refunded.Note: This requirement applies only to apps that use the Google Play Billing
Library version 2.0 and newer. This requirement doesn't apply if you use an older
version of the Google Play Billing Library, or if you use the AIDL API.

Google Play supports purchasing products from inside of your app (in-app) or
outside of your app (out-of-app). In order for Google Play to ensure a
consistent purchase experience regardless of where the user purchases your
product, you must acknowledge all purchases received through the Google Play
Billing Library as soon as possible after granting entitlement to the user. If
you do not acknowledge a purchase within three days, the user automatically
receives a refund, and Google Play revokes the purchase. For
pending transactions (new in version 2.0), the three-day window
starts when the purchase has moved to the SUCCESS state and does not apply
while the purchase is in a PENDING state.

For subscriptions, you must acknowledge any purchase that has a new purchase
token. This means that all initial purchases, plan changes, and re-signups need
to be acknowledged, but you do not need to acknowledge subsequent renewals. To
determine if a purchase needs acknowledgment, you can check the acknowledgement
field in the purchase.

The Purchase object now includes an
isAcknowledged()
method that indicates whether a purchase has been acknowledged. In addition, the
Google Play Developer API includes acknowledgement boolean values for both
Purchases.products
and Purchases.subscriptions.
Before acknowledging a purchase, be sure to use these methods to determine if
the purchase has already been acknowledged.

You can acknowledge a purchase by using one of the following methods:

For consumable products, use consumeAsync(), found in the client API.

For products that aren't consumed, use acknowledgePurchase(), found in the
client API.

Developer payload is supported

Version 2.0 of the Google Play Billing library adds support for developer
payload—arbitrary strings that can be attached to purchases. You can
attach a developer payload parameter to a purchase, but only when the purchase
is acknowledged or consumed. This is unlike developer payload in AIDL, where the
payload could be specified when launching the purchase flow. Because purchases
can now be initiated from outside of your app, this change
ensures that you always have an opportunity to add a payload to purchases.

Pending transactions

With version 2.0 of the Google Play Billing library, you must support
purchases where additional action is required before granting entitlement. For
example, a user might choose to purchase your in-app product at a physical store
using cash. This means that the transaction is completed outside of your app. In
this scenario, you should grant entitlement only after the user has completed
the transaction.

Use Purchase.getPurchaseState()
to determine whether the purchase state is PURCHASED or PENDING. Note that
you should grant entitlement only when the state is PURCHASED. You should
check for Purchase status updates by doing the following:

In addition, the Google Play Developer API includes a PENDING state
for Purchases.products.
Pending transactions are not supported for
subscriptions.

This release also introduces a new real-time developer notification type,
OneTimeProductNotification. This notification type contains a single message
whose value is either ONE_TIME_PRODUCT_PURCHASED or
ONE_TIME_PRODUCT_CANCELED. This notification type is sent only for purchases
associated with delayed forms of payment, such as cash.

When acknowledging pending purchases, be sure to acknowledge only when the
purchase state is SUCCESS and not PENDING.

Note: Pending transactions can be tested using license testers. In addition to
two test credit cards, license testers have access to two new test instruments
for delayed forms of payment which automatically complete or cancel after a
couple of minutes. While testing your application, you should verify that your
application does not grant entitlement or acknowledge the purchase immediately
after purchasing with either of these two new instruments. When purchasing using
the new test instrument that automatically completes, you should verify that
your application grants entitlement and acknowledges the purchase once the
purchase completes.

API changes

Version 2.0 of the Google Play Billing library contains several API changes to
support new features and clarify existing functionality.

consumeAsync

consumeAsync()
now takes a
ConsumeParams object
instead of a purchaseToken. ConsumeParams contains the purchaseToken as
well as an optional developer payload.

The previous version of consumeAsync() has been removed in this release.

queryPurchaseHistoryAsync

To minimize confusion,
queryPurchaseHistoryAsync()
now returns a
PurchaseHistoryRecord
object instead of a Purchase object. The PurchaseHistoryRecord object is the
same as a Purchase object, except that it reflects only the values returned by
queryPurchaseHistoryAsync() and does not contain the autoRenewing,
orderId, and packageName fields. Note that nothing has changed with the
returned data—queryPurchaseHistoryAsync() returns the same data as
before.

BillingResult return values

APIs that previously returned a BillingResponse integer value now return a
BillingResult
object. BillingResult contains the BillingResponse integer as well as a
debug string that you can use to diagnose errors. The debug string uses an en-US
locale and is not meant to be shown to end users.

Summary of changes

Added the launchPriceChangeConfirmationFlow API, which prompts users to
review a pending change to a subscription price.

Added support for a new proration mode, DEFERRED, when upgrading or
downgrading a user's subscription.

In the BillingFlowParams class, replaced setSku() with setSkuDetails().

Minor bug fixes and code optimizations.

Price change confirmation

You can now change the price of a subscription in Google Play Console and prompt
users to review and accept the new price when they enter your app.

To use this API, create a PriceChangeFlowParams object by using the
skuDetails of the subscription product, and then call
launchPriceChangeConfirmationFlow(). Implement the
PriceChangeConfirmationListener to handle the result when the price change
confirmation flow finishes, as shown in the following code snippet:

The price change confirmation flow displays a dialog containing the new pricing
information, asking users to accept the new price. This flow returns a
response code of type
BillingClient.BillingResponse.

New proration mode

When upgrading or downgrading a user's subscription, you can use a new proration
mode, DEFERRED. This mode updates the user's subscription when it next
renews. To learn more about how to set this proration mode, see Set proration
mode.

New method for setting SKU details

In the BillingFlowParams class, the setSku() method has been deprecated.
This change serves to optimize the Google Play Billing flow.

When constructing a new instance of BillingFlowParams in your in-app billing
client, we recommend that you instead work with the JSON object directly using
setSkuDetails(), as shown in the following code snippet:

In the BillingFlowParams Builder class, the setSku() method has been
deprecated. Instead, use the setSkuDetails() method, as shown in the following
code snippet. The object passed into setSkuDetails() object comes from the
querySkuDetailsAsync()
method.

Developers used to be able to set a boolean flag to charge a prorated amount for a subscription
upgrade request. Given that we are supporting ProrationMode, which contains more detailed
proration instruction, this boolean flag is no longer supported.

Bug fixes

Developer preview launched, aimed to simplify the development process when it comes to billing,
allowing developers to focus their efforts on implementing logic specific to the Android app, such as
application architecture and navigation structure.

The library includes several convenient classes and features for you to use when integrating your
Android apps with the Google Play Billing API. The library also provides an abstraction layer on top of
the Android Interface Definition Language (AIDL) service, making it easier for developers to define
the interface between the app and the Google Play Billing API.

Content and code samples on this page are subject to the licenses described in the Content License. Java is a registered trademark of Oracle and/or its affiliates.