This document describes how to migrate from Google Play Billing Library (PBL) 6 or 7 to PBL 8 and how to integrate with the new optional subscription capabilities.

For a full list of the changes in version 8.0.0, refer to the release notes.

Overview

PBL 8 contains improvements to existing APIs along with the removal of previously deprecated APIs. This version of the library also includes new APIs for one-time products.

Backward-compatibility for PBL upgrade

To migrate to PBL 8, you need to update or remove some of your existing API references from your app, as described in the release notes and later in this migration guide.

Upgrade from PBL 6 or 7 to PBL 8

To upgrade from PBL 6 or 7 to PBL 8, do the following steps:

  1. Update the Play Billing Library dependency version in your app's build.gradle file.

    dependencies {
      def billingVersion = 8.0.0
      implementation "com.android.billingclient:billing:$billingVersion"
    }
    
  2. (Applicable only for upgrade from PBL 6 to PBL 8). Handle subscription related API changes in your app.

    The following table lists the subscription related APIs that are removed in PBL 8 and the corresponding alternate API that you must use in your app.

    Previously deprecated API removed in PBL 8 Alternate API to use
    setOldSkuPurchaseToken setOldPurchaseToken
    setReplaceProrationMode setSubscriptionReplacementMode
    setReplaceSkusProrationMode setSubscriptionReplacementMode
  3. Update the implementation of the queryProductDetailsAsync method.

    There is a change in the signature of the ProductDetailsResponseListener.onProductDetailsResponse method, which requires changes in your app for the queryProductDetailsAsync implementation. For more information, see Show products available to buy.

  4. Handle the removed APIs.

    Upgrade from

    PBL 8 no longer supports the APIs listed in the following table. If your implementation uses any of these removed APIs, refer to the table for their corresponding alternate APIs.

    Previously deprecated API removed in PBL 8 Alternate API to use
    queryPurchaseHistoryAsync APIs See Query Purchase History
    querySkuDetailsAsync queryProductDetailsAsync
    enablePendingPurchases() (API without parameters) enablePendingPurchases(PendingPurchaseParams params)
    Note that the deprecated enablePendingPurchases() is functionally equivalent to enablePendingPurchases(PendingPurchasesParams.newBuilder().enableOneTimeProducts().build()).
    queryPurchasesAsync(String skuType, PurchasesResponseListener listener) queryPurchasesAsync
    BillingClient.Builder.enableAlternativeBilling BillingClient.Builder.enableUserChoiceBilling
    AlternativeBillingListener UserChoiceBillingListener
    AlternativeChoiceDetails UserChoiceDetails

    Upgrade from

    The following table lists the APIs that are removed in PBL 8, and the corresponding alternate APIs that you must use in your app.

    Previously deprecated API removed in PBL 8 Alternate API to use
    queryPurchaseHistoryAsync APIs See Query Purchase History
    querySkuDetailsAsync queryProductDetailsAsync
    enablePendingPurchases() (API without parameters) enablePendingPurchases(PendingPurchaseParams params)
    Note that the deprecated enablePendingPurchases() is functionally equivalent to enablePendingPurchases(PendingPurchasesParams.newBuilder().enableOneTimeProducts().build()).
    queryPurchasesAsync(String skuType, PurchasesResponseListener listener) queryPurchasesAsync

  5. (Recommended) Enable automatic service reconnection.

    The Play Billing Library can attempt to automatically re-establish the service connection if an API call is made while the service is disconnected. For more information, see Enable automatic service reconnection.

  6. Optional changes.