This guide describes how to integrate with the APIs to support external offers in eligible apps and regions. To learn more about the external offers program including eligibility requirements and geographic scope see program requirements.
Play Billing Library setup
To use the external offers APIs, add version 6.2.1 or higher of the Play Billing Library dependency to your Android app. If you need to migrate from an earlier version, follow the instructions in the migration guide before you attempt to implement external offers.
Connect to Google Play
The first steps in the integration process are the same as the ones described in
the billing integration guide, with a few modifications when
initializing your BillingClient
:
- You need to call a new method to indicate that you want to use external
offers:
enableExternalOffer
.
The following example demonstrates initializing a BillingClient
with these
modifications:
Kotlin
var billingClient = BillingClient.newBuilder(context)
.enableExternalOffer()
.build()
Java
private BillingClient billingClient = BillingClient.newBuilder(context)
.enableExternalOffer()
.build();
After you initialize the BillingClient
, you need to establish a connection to
Google Play as described in the integration guide.
Check availability
Your app should confirm external offers are available by calling
isExternalOfferAvailableAsync
.
This API returns BillingResponseCode.OK
if external offers are available.
See response handling for details on how your app should
respond to other response codes.
Kotlin
billingClient.isExternalOfferAvailableAsync(
object : ExternalOfferAvailabilityListener {
override fun onExternalOfferAvailabilityResponse(
billingResult: BillingResult) {
if (billingResult.responseCode != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors,
// handling external offers unavailable, etc.
return
}
// External offers are available. Continue with steps in the
// guide.
})
Java
billingClient.isExternalOfferAvailableAsync(
new ExternalOfferAvailabilityListener() {
@Override
public void onExternalOfferAvailabilityResponse(
BillingResult billingResult) {
if (billingResult.getResponseCode() != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors,
// handling external offers being unavailable, etc.
return;
}
// External offers are available. Continue with steps in the
// guide.
}
});
Prepare an external transaction token
To report an external transaction to Google Play, you must have an external
transaction token generated from the Play Billing Library. A new external
transaction token must be generated each time the user visits an external
website through the external offers API. This can be done by calling the
createExternalOfferReportingDetailsAsync
API. This token should be
generated immediately before the user is directed outside the app. It should
never be cached and a new one should be generated each time the user is directed
outside the app.
Kotlin
billingClient.createExternalOfferReportingDetailsAsync(
object : ExternalOfferReportingDetailsListener {
override fun onExternalOfferReportingDetailsResponse(
billingResult: BillingResult,
externalOfferReportingDetails: ExternalOfferReportingDetails?) {
if (billingResult.responseCode != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors.
return
}
val externalTransactionToken =
externalOfferReportingDetails?.externalTransactionToken
// Persist the transaction token locally. Pass it to the external
// website when showExternalOfferInformationDialog is called.
}
})
Java
billingClient.createExternalOfferReportingDetailsAsync(
new ExternalOfferReportingDetailsListener() {
@Override
public void onExternalOfferReportingDetailsResponse(
BillingResult billingResult,
@Nullable ExternalOfferReportingDetails
externalOfferReportingDetails) {
if (billingResult.getResponseCode() != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors.
return;
}
String transactionToken =
externalOfferReportingDetails.getExternalTransactionToken();
// Persist the external transaction token locally. Pass it to the
// external website when showExternalOfferInformationDialog is
// called.
}
});
Information dialog for users
To integrate with external offers, your eligible app must show an information
screen which helps users understand that they are about to be directed outside
the app to an external website. The information screen must be shown to users by
calling the showExternalOfferInformationDialog
API before linking to an
external offer each time.
Kotlin
// An activity reference from which the external offers information dialog
// will be launched.
val activity : Activity = ...;
val listener : ExternalOfferInformationDialogListener =
ExternalOfferInformationDialogListener {
override fun onExternalOfferInformationDialogResponse(
billingResult: BillingResult){
// Check billingResult
}
}
val billingResult = billingClient.showExternalOfferInformationDialog(
activity, listener)
Java
// An activity reference from which the external offers information dialog
// will be launched.
Activity activity = ...;
ExternalOfferInformationDialogListener listener =
new ExternalOfferInformationDialogListener() {
@Override
public void onExternalOfferInformationDialogResponse(
BillingResult billingResult) {
if (billingResult.responseCode != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors.
}
// Open the external website, passing along the external transaction
// token as a URL parameter. If the user purchases an item, be sure
// to report the transaction to Google Play.
}
}
BillingResult billingResult =
billingClient.showExternalOfferInformationDialog(activity, listener);
If this method returns BillingResponseCode.OK
, then your app can proceed to
direct the user to the external website. If the method returns
BillingResponseCode.USER_CANCELED
, your app must not continue opening the
website.
Report transactions to Google Play
All external transactions must be reported to Google Play
by calling the Google Play Developer API from your backend. External transactions
must be reported while providing an
externalTransactionToken
obtained using the
createExternalOfferReportingDetailsAsync
API. If a user makes multiple
purchases, you may use the same
externalTransactionToken
to report each purchase. To learn how to report a
transaction, see the backend integration guide.
Response handling
When an error occurs, the methods isExternalOfferAvailableAsync
,
createExternalOfferReportingDetailsAsync
, and
showExternalOfferInformationDialog
might return responses other than
BillingResponseCode.OK
. Consider handling these response codes as follows:
ERROR
: This is an internal error. Don't proceed with the transaction or opening the external website. Retry again by callingshowExternalOfferInformationDialog()
to display the information dialog to the user the next time you attempt to direct the user outside the app.FEATURE_NOT_SUPPORTED
: The external offers APIs are not supported by the Play Store on the current device. Don't proceed with the transaction or opening the external website.USER_CANCELED
: Don't proceed with opening the external website. CallshowExternalOfferInformationDialog()
again to display the information dialog to the user the next time you attempt to direct the user outside of the app.BILLING_UNAVAILABLE
: The transaction is not eligible for external offers and therefore shouldn't proceed under this program. This is either because the user is not in an eligible country for this program or your account has not been successfully enrolled in the program. If it's the latter, check your enrollment status in the Play Developer Console.DEVELOPER_ERROR
: There is an error with the request. Use the debug message to identify and correct the error before proceeding.NETWORK_ERROR, SERVICE_DISCONNECTED, SERVICE_UNAVAILABLE
: These are transient errors that should be handled with an appropriate retry policy. In the case ofSERVICE_DISCONNECTED
, re-establish a connection with Google Play before retrying.
Test external offers
License testers should be used to test your external offers integration. You won't be invoiced for transactions that have been initiated by license tester accounts. See Test in-app billing with application licensing for more information on configuring license testers.
Next steps
Once you've finished in-app integration, you're ready to integrate your backend.