BillingClient

public abstract class BillingClient


Main interface for communication between the library and user application code.

It provides convenience methods for in-app billing. You can create one instance of this class for your application and use it to process in-app billing operations. It provides synchronous (blocking) and asynchronous (non-blocking) methods for many common in-app billing operations.

It's strongly recommended that you instantiate only one BillingClient instance at one time to avoid multiple PurchasesUpdatedListener#onPurchasesUpdated callbacks for a single event.

All methods annotated with AnyThread can be called from any thread and all the asynchronous callbacks will be returned on the same thread. Methods annotated with UiThread should be called from the Ui thread and all the asynchronous callbacks will be returned on the Ui thread as well.

After instantiating, you must perform setup in order to start using the object. To perform setup, call the startConnection method and provide a listener; that listener will be notified when setup is complete, after which (and not before) you may start calling other methods. After setup is complete, you will typically want to request an inventory of owned items and subscriptions. See queryPurchasesAsync and queryProductDetailsAsync.

When you are done with this object, don't forget to call endConnection to ensure proper cleanup. This object holds a binding to the in-app billing service and the manager to handle broadcast events, which will leak unless you dispose it correctly. If you created the object inside the Activity#onCreate method, then the recommended place to dispose is the Activity#onDestroy method. After cleanup, it cannot be reused again for connection.

To get library logs inside Android logcat, set corresponding logging level. E.g.: adb shell setprop log.tag.BillingClient VERBOSE

Summary

Nested types

@Retention(value = java.lang.annotation.RetentionPolicy.SOURCE)
public annotation BillingClient.BillingResponseCode

Possible response codes.

public final class BillingClient.Builder

Builder to configure and create a BillingClient instance.

@Retention(value = java.lang.annotation.RetentionPolicy.SOURCE)
public annotation BillingClient.ConnectionState

Connection state of billing client.

@Retention(value = java.lang.annotation.RetentionPolicy.SOURCE)
public annotation BillingClient.FeatureType

Features/capabilities supported by isFeatureSupported.

@Retention(value = java.lang.annotation.RetentionPolicy.SOURCE)
public annotation BillingClient.ProductType

Supported Product types.

@Retention(value = java.lang.annotation.RetentionPolicy.SOURCE)
public annotation BillingClient.SkuType

This annotation is deprecated.

Use ProductType instead.

Public constructors

Public methods

abstract void

Acknowledges in-app purchases.

abstract void
consumeAsync(
    ConsumeParams consumeParams,
    ConsumeResponseListener listener
)

Consumes a given in-app product.

abstract void

Creates alternative billing only purchase details that can be used to report a transaction made via alternative billing without user choice to use Google Play billing.

abstract void

Creates purchase details that can be used to report a transaction made via external offer.

abstract void

Closes the connection and releases all held resources such as service connections.

abstract void

Gets the billing config, which stores configuration used to perform billing operations.

abstract int

Get the current billing client connection state.

abstract void

Checks the availability of offering alternative billing without user choice to use Google Play billing.

abstract void

Checks the availability of providing external offer.

abstract BillingResult

Checks if the specified feature or capability is supported by the Play Store.

abstract boolean

Checks if the client is currently connected to the service, so that requests to other methods will succeed.

abstract BillingResult

Initiates the billing flow for an in-app purchase or subscription.

static BillingClient.Builder

Constructs a new Builder instance.

abstract void

Performs a network query the details of products available for sale in your app.

abstract void
queryPurchaseHistoryAsync(
    QueryPurchaseHistoryParams queryPurchaseHistoryParams,
    PurchaseHistoryResponseListener listener
)

Returns the most recent purchase made by the user for each product, even if that purchase is expired, canceled, or consumed.

abstract void

This method is deprecated.

Use queryPurchaseHistoryAsync instead;

abstract void
queryPurchasesAsync(
    QueryPurchasesParams queryPurchasesParams,
    PurchasesResponseListener listener
)

Returns purchases details for currently owned items bought within your app.

abstract void

This method is deprecated.

Use queryPurchasesAsync instead.

abstract void

This method is deprecated.

Use queryProductDetailsAsync instead.

abstract BillingResult

Shows the alternative billing only information dialog on top of the calling app.

abstract BillingResult

Shows the external offer information dialog on top of the calling app.

abstract BillingResult
showInAppMessages(
    Activity activity,
    InAppMessageParams params,
    InAppMessageResponseListener listener
)

Overlays billing related messages on top of the calling app.

abstract void

Starts up BillingClient setup process asynchronously.

Public constructors

BillingClient

public BillingClient()

Public methods

acknowledgePurchase

public abstract void acknowledgePurchase(
    AcknowledgePurchaseParams params,
    AcknowledgePurchaseResponseListener listener
)

Acknowledges in-app purchases.

Developers are required to acknowledge that they have granted entitlement for all in-app purchases for their application.

Warning! All purchases require acknowledgement. Failure to acknowledge a purchase will result in that purchase being refunded. For one-time products ensure you are using consumeAsync which acts as an implicit acknowledgement or you can explicitly acknowledge the purchase via this method. For subscriptions use acknowledgePurchase. Please refer to the integration guide for more details.

Parameters
AcknowledgePurchaseParams params

Params specific to this acknowledge purchase request.

AcknowledgePurchaseResponseListener listener

The listener for the result of the acknowledge operation returned asynchronously through the callback with the BillingResponseCode.

consumeAsync

public abstract void consumeAsync(
    ConsumeParams consumeParams,
    ConsumeResponseListener listener
)

Consumes a given in-app product. Consuming can only be done on an item that's owned, and as a result of consumption, the user will no longer own it.

Consumption is done asynchronously and the listener receives the callback specified upon completion.

Warning! All purchases require acknowledgement. Failure to acknowledge a purchase will result in that purchase being refunded. For one-time products ensure you are using this method which acts as an implicit acknowledgement or you can explicitly acknowledge the purchase via acknowledgePurchase. For subscriptions use acknowledgePurchase. Please refer to https://developer.android.com/google/play/billing/billing_library_overview#acknowledge for more details.

Parameters
ConsumeParams consumeParams

Params specific to consumimg a purchase.

ConsumeResponseListener listener

The listener for the result of the consume operation returned asynchronously through the callback with the purchase token and BillingResponseCode.

createAlternativeBillingOnlyReportingDetailsAsync

public abstract void createAlternativeBillingOnlyReportingDetailsAsync(
    AlternativeBillingOnlyReportingDetailsListener listener
)

Creates alternative billing only purchase details that can be used to report a transaction made via alternative billing without user choice to use Google Play billing.

Parameters
AlternativeBillingOnlyReportingDetailsListener listener

The listener for the response of the create alternative billing only reporting details flow.

createExternalOfferReportingDetailsAsync

public abstract void createExternalOfferReportingDetailsAsync(
    ExternalOfferReportingDetailsListener listener
)

Creates purchase details that can be used to report a transaction made via external offer.

Parameters
ExternalOfferReportingDetailsListener listener

The listener for the response of the create external offer reporting details flow.

endConnection

public abstract void endConnection()

Closes the connection and releases all held resources such as service connections.

Call this method once you are done with this BillingClient reference, and when Activity or Fragment is destroyed to avoid memory leak.

getBillingConfigAsync

public abstract void getBillingConfigAsync(
    GetBillingConfigParams params,
    BillingConfigResponseListener listener
)

Gets the billing config, which stores configuration used to perform billing operations.

Note: This data can change and should not be cached.

Parameters
GetBillingConfigParams params

Params specific to this get billing config request.

BillingConfigResponseListener listener

The listener for the response of the get billing config flow.

getConnectionState

public abstract int getConnectionState()

Get the current billing client connection state.

Returns
int

The ConnectionState corresponding to the current client connection state.

isAlternativeBillingOnlyAvailableAsync

public abstract void isAlternativeBillingOnlyAvailableAsync(
    AlternativeBillingOnlyAvailabilityListener listener
)

Checks the availability of offering alternative billing without user choice to use Google Play billing.

Note: This data can change and should not be cached.

Parameters
AlternativeBillingOnlyAvailabilityListener listener

The listener for the response of the alternative billing only availability.

isExternalOfferAvailableAsync

public abstract void isExternalOfferAvailableAsync(
    ExternalOfferAvailabilityListener listener
)

Checks the availability of providing external offer.

Note: This data can change and should not be cached.

Parameters
ExternalOfferAvailabilityListener listener

The listener for the response of the external offer availability.

isFeatureSupported

public abstract BillingResult isFeatureSupported(String feature)

Checks if the specified feature or capability is supported by the Play Store.

Parameters
String feature

One of the FeatureType constants.

Returns
BillingResult

BillingResponseCode#OK if the feature is supported or FEATURE_NOT_SUPPORTED otherwise.

isReady

public abstract boolean isReady()

Checks if the client is currently connected to the service, so that requests to other methods will succeed.

Returns true if the client is currently connected to the service, false otherwise.

Note: It also means that INAPP items are supported for purchasing, queries and all other actions. If you need to check support for SUBSCRIPTIONS or something different, use isFeatureSupported method.

launchBillingFlow

public abstract BillingResult launchBillingFlow(Activity activity, BillingFlowParams params)

Initiates the billing flow for an in-app purchase or subscription.

It will show the Google Play purchase screen. The result will be delivered via the PurchasesUpdatedListener interface implementation set by Builder#setListener.

Parameters
Activity activity

An activity reference from which the billing flow will be launched.

BillingFlowParams params

Params specific to the launch billing flow request.

Returns
BillingResult

The result of the launch billing flow operation. ITEM_ALREADY_OWNED if the user already owns the item being purchased, BillingResponseCode#ITEM_UNAVAILABLE if the item is not available to be purchased, and BillingResponseCode#USER_CANCELED if the user dismissed the purchase flow.

newBuilder

public static BillingClient.Builder newBuilder(Context context)

Constructs a new Builder instance.

Parameters
Context context

It will be used to get an application context to bind to the in-app billing service.

queryProductDetailsAsync

public abstract void queryProductDetailsAsync(
    QueryProductDetailsParams params,
    ProductDetailsResponseListener listener
)

Performs a network query the details of products available for sale in your app.

Parameters
QueryProductDetailsParams params

Params containing list of Product where each product contains product id and ProductType.

ProductDetailsResponseListener listener

The listener for the result of the query operation returned asynchronously through the callback with the BillingResponseCode.

queryPurchaseHistoryAsync

public abstract void queryPurchaseHistoryAsync(
    QueryPurchaseHistoryParams queryPurchaseHistoryParams,
    PurchaseHistoryResponseListener listener
)

Returns the most recent purchase made by the user for each product, even if that purchase is expired, canceled, or consumed.

Parameters
QueryPurchaseHistoryParams queryPurchaseHistoryParams

Params specific to this query request.

PurchaseHistoryResponseListener listener

The listener for the result of the query returned asynchronously through the callback with the BillingResult and the list of PurchaseHistoryRecord.

queryPurchaseHistoryAsync

public abstract void queryPurchaseHistoryAsync(
    String skuType,
    PurchaseHistoryResponseListener listener
)

Returns the most recent purchase made by the user for each SKU, even if that purchase is expired, canceled, or consumed.

Parameters
String skuType

The type of SKU, either "inapp" or "subs" as in SkuType.

PurchaseHistoryResponseListener listener

The listener for the result of the query returned asynchronously through the callback with the BillingResult and the list of PurchaseHistoryRecord.

queryPurchasesAsync

public abstract void queryPurchasesAsync(
    QueryPurchasesParams queryPurchasesParams,
    PurchasesResponseListener listener
)

Returns purchases details for currently owned items bought within your app.

Only active subscriptions and non-consumed one-time purchases are returned. This method uses a cache of Google Play Store app without initiating a network request.

Note: It's recommended for security purposes to go through purchases verification on your backend (if you have one) by calling one of the following APIs: https://developers.google.com/android-publisher/api-ref/purchases/products/get https://developers.google.com/android-publisher/api-ref/purchases/subscriptions/get

Parameters
QueryPurchasesParams queryPurchasesParams

Params specific to this query request.

PurchasesResponseListener listener

The listener for the result of the query returned asynchronously through the callback with the BillingResult and the list of Purchase.

queryPurchasesAsync

public abstract void queryPurchasesAsync(String skuType, PurchasesResponseListener listener)

Returns purchases details for currently owned items bought within your app.

Only active subscriptions and non-consumed one-time purchases are returned. This method uses a cache of Google Play Store app without initiating a network request.

Note: It's recommended for security purposes to go through purchases verification on your backend (if you have one) by calling one of the following APIs: https://developers.google.com/android-publisher/api-ref/purchases/products/get https://developers.google.com/android-publisher/api-ref/purchases/subscriptions/get

Parameters
String skuType

The type of SKU, either "inapp" or "subs" as in SkuType.

PurchasesResponseListener listener

The listener for the result of the query returned asynchronously through the callback with the BillingResult and the list of Purchase.

querySkuDetailsAsync

public abstract void querySkuDetailsAsync(
    SkuDetailsParams params,
    SkuDetailsResponseListener listener
)

Performs a network query to get SKU details and return the result asynchronously.

Parameters
SkuDetailsParams params

Params specific to this query request.

SkuDetailsResponseListener listener

The listener for the result of the query operation returned asynchronously through the callback with the BillingResponseCode and the list of SkuDetails.

showAlternativeBillingOnlyInformationDialog

public abstract BillingResult showAlternativeBillingOnlyInformationDialog(
    Activity activity,
    AlternativeBillingOnlyInformationDialogListener listener
)

Shows the alternative billing only information dialog on top of the calling app.

If this dialog has previously been shown and acknowledged by the user on the app and device, it won't be shown again.

The listener will be invoked on the UI thread on completion.

Parameters
Activity activity

An activity reference to host the rendering of the alternative billing only dialog.

AlternativeBillingOnlyInformationDialogListener listener

The listener for the response of the alternative billing only dialog.

Returns
BillingResult

BillingResponseCode#OK if the request is successfully submitted to Play Store, or an error code otherwise.

showExternalOfferInformationDialog

public abstract BillingResult showExternalOfferInformationDialog(
    Activity activity,
    ExternalOfferInformationDialogListener listener
)

Shows the external offer information dialog on top of the calling app.

The listener will be invoked on the UI thread on completion.

Parameters
Activity activity

An activity reference to host the rendering of the external offer information dialog.

ExternalOfferInformationDialogListener listener

The listener for the response of the external offer information dialog.

Returns
BillingResult

BillingResponseCode#OK if the request is successfully submitted to Play Store, or an error code otherwise.

showInAppMessages

public abstract BillingResult showInAppMessages(
    Activity activity,
    InAppMessageParams params,
    InAppMessageResponseListener listener
)

Overlays billing related messages on top of the calling app.

For example, show a message to inform users that their subscription payment has been declined and provide options to take them to fix their payment method.

Callback will be returned on UI thread.

Parameters
Activity activity

An activity reference to host the rendering of in-app messages.

InAppMessageParams params

Params specific to this show in-app messages request.

InAppMessageResponseListener listener

The listener for the result response of the in-app messaging flow.

Returns
BillingResult

BillingResponseCode#OK if the request is successfully submitted to Play Store, or an error code otherwise.

startConnection

public abstract void startConnection(BillingClientStateListener listener)

Starts up BillingClient setup process asynchronously. You will be notified through the BillingClientStateListener listener when the setup process is complete.

Parameters
BillingClientStateListener listener

The listener to notify when the setup process is complete.