本指南介绍了如何与相关 API 集成,从而在符合条件的应用和地区支持外部优惠。如需详细了解外部优惠计划(包括资格要求和地理范围),请参阅计划要求。
Play 结算库设置
如需使用外部优惠 API,请向您的 Android 应用添加 6.2.1 版或更高版本的 Play 结算库依赖项。如果您需要从早期版本迁移,请先按照迁移指南中的说明操作,然后再尝试实现外部优惠。
连接到 Google Play
集成流程的最初步骤与结算集成指南中所述的一些步骤相同,在初始化 BillingClient
时需要进行一些修改:
- 您需要调用新方法来表明您要使用外部优惠:
enableExternalOffer
。
以下示例演示了如何通过这些调整来初始化 BillingClient
:
Kotlin
var billingClient = BillingClient.newBuilder(context)
.enableExternalOffer()
.build()
Java
private BillingClient billingClient = BillingClient.newBuilder(context)
.enableExternalOffer()
.build();
初始化 BillingClient
后,您需要按照集成指南中的说明与 Google Play 建立连接。
查看商品库存状况
您的应用应通过调用 isExternalOfferAvailableAsync
来确认外部优惠是否可用。
如果外部优惠可用,此 API 会返回 BillingResponseCode.OK
。如需详细了解您的应用应如何响应其他响应代码,请参阅响应处理。
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.
}
});
准备外部交易令牌
您必须拥有通过 Play 结算库生成的外部交易令牌,才能向 Google Play 报告外部交易。每当用户通过外部优惠 API 访问外部网站时,都必须生成新的外部交易令牌。这可以通过调用 createExternalOfferReportingDetailsAsync
API 来做到。此令牌应在用户被定向到应用外部之前立即生成。切勿缓存该令牌,并且每次将用户定向到应用外部时都应该生成新令牌。
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.
}
});
面向用户的信息对话框
如需与外部优惠集成,符合条件的应用必须显示一个信息界面,帮助用户了解他们将从应用外部转到外部网站。每次关联到外部优惠之前,必须通过调用 showExternalOfferInformationDialog
API 向用户显示信息界面。
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);
如果此方法返回 BillingResponseCode.OK
,您的应用可以继续将用户定向到外部网站。如果该方法返回 BillingResponseCode.USER_CANCELED
,您的应用不得继续打开网站。
向 Google Play 报告交易
所有外部交易都必须通过从后端调用 Google Play Developer API 来报告给 Google Play。在提供使用 createExternalOfferReportingDetailsAsync
API 获取的 externalTransactionToken
时,必须报告外部交易。如果用户进行了多次购买交易,您可以使用同一 externalTransactionToken
报告每笔购买交易。如需了解如何报告交易,请参阅后端集成指南。
响应处理
发生错误时,isExternalOfferAvailableAsync
、createExternalOfferReportingDetailsAsync
和 showExternalOfferInformationDialog
方法可能会返回 BillingResponseCode.OK
以外的响应。请考虑按如下方式处理这些响应代码:
ERROR
:这是内部错误。请勿继续交易或打开外部网站。下次您尝试将用户定向到应用之外时,请调用showExternalOfferInformationDialog()
向用户显示信息对话框,以便重试。FEATURE_NOT_SUPPORTED
:当前设备上的 Play 商店不支持外部优惠 API。请勿继续交易或打开外部网站。USER_CANCELED
:不继续打开外部网站。当您下次尝试将用户定向到应用之外时,请再次调用showExternalOfferInformationDialog()
以向用户显示信息对话框。BILLING_UNAVAILABLE
:交易不符合外部优惠的条件,因此不应按照此计划继续进行。这是因为用户不在符合此计划条件的国家/地区,或者您的账号未成功注册此计划。如果是后一种情况,请在 Play 管理中心内检查您的注册状态。DEVELOPER_ERROR
:请求中存在错误。使用调试消息找出并更正错误,然后再继续交易。NETWORK_ERROR, SERVICE_DISCONNECTED, SERVICE_UNAVAILABLE
:这些是暂时性错误,应使用适当的重试政策进行处理。如果发生SERVICE_DISCONNECTED
错误,请重新与 Google Play 建立连接,然后重试。
测试外部优惠
应使用许可测试人员来测试您的外部产品集成。我们不会为许可测试人员帐号发起的交易开具账单。如需详细了解如何配置许可测试人员,请参阅使用应用许可来测试应用内购结算功能。
后续步骤
完成应用内集成后,您就可以集成后端了。