本指南介绍了如何在符合条件的应用中集成 API 以仅提供备用结算(即不含用户选择)。要了解有关这些计划的更多信息,包括资格要求和地理范围,请参阅关于备用结算。
Play 结算库设置
将Play 结算库依赖项添加到您的 Android 应用。要使用备用结算 API,您需要使用 6.1 或更高版本。
连接到 Google Play
集成过程中的第一步与Google Play 结算集成指南中描述的步骤相同,但在初始化 BillingClient 时有一些修改。
- 您需要调用一个新方法来表明您的应用仅使用备用结算系统:
enableAlternativeBillingOnly
。
以下示例演示了通过这些修改初始化 BillingClient
的过程
Kotlin
var billingClient = BillingClient.newBuilder(context)
.enableAlternativeBillingOnly()
.build()
Java
private BillingClient billingClient = BillingClient.newBuilder(context)
.enableAlternativeBillingOnly()
.build();
初始化 BillingClient
后,您需要按照集成指南中的说明与 Google Play 建立连接。
检查可用性
您的应用应通过调用 isAlternativeBillingOnlyAvailableAsync
来确认仅备用结算是否可用。
如果仅备用结算可用,此 API 将返回 BillingResponseCode.OK。有关您的应用应如何响应其他响应代码的详细信息,请参阅响应处理。
Kotlin
billingClient.isAlternativeBillingOnlyAvailableAsync(object:
AlternativeBillingOnlyAvailabilityListener {
override fun onAlternativeBillingOnlyAvailabilityResponse(
billingResult: BillingResult) {
if (billingResult.responseCode != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors,
// handling alternative billing only being unavailable, etc.
return
}
// Alternative billing only is available. Continue with steps in
// the guide.
}
});
Java
billingClient.isAlternativeBillingOnlyAvailable(
new AlternativeBillingOnlyAvailabilityListener() {
@Override
public void onAlternativeBillingOnlyAvailabilityResponse(
BillingResult billingResult) {
if (billingResult.getResponseCode() != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors,
// handling alternative billing only being unavailable,
// etc.
return;
}
// Alternative billing only is available. Continue with steps in
// the guide.
}
});
面向用户的信息对话框
要仅与备用结算集成,您的合格应用必须显示一个信息屏幕,帮助用户了解结算将不由 Google Play 管理。每次开始备用结算流程之前,必须通过调用 showAlternativeBillingOnlyInformationDialog
API 向用户显示信息屏幕。如果用户已经确认过对话框,使用此 API 通常不会导致对话框再次显示。在用户清除设备上的缓存等情况下,对话框可能会再次显示给用户。
Kotlin
// An activity reference from which the alternative billing only information
// dialog will be launched.
val activity : Activity = ...;
val listener : AlternativeBillingOnlyInformationDialogListener =
AlternativeBillingOnlyInformationDialogListener {
override fun onAlternativeBillingOnlyInformationDialogResponse(
billingResult: BillingResult) {
// check billingResult
}
}
val billingResult =
billingClient.showAlternativeBillingOnlyInformationDialog(activity,
listener)
Java
// An activity reference from which the alternative billing only information
// dialog will be launched.
Activity activity = ...;
AlternativeBillingOnlyInformationDialogListener listener =
new AlternativeBillingOnlyInformationDialogListener() {
@Override
public void onAlternativeBillingOnlyInformationDialogResponse(
BillingResult billingResult) {
// check billingResult
}
};
BillingResult billingResult =
billingClient.showAlternativeBillingOnlyInformationDialog(activity,
listener);
如果此方法返回 BillingResponseCode.OK,则您的应用可以继续进行交易。对于 BillingResponseCode.USER_CANCELED 的情况,您的应用应再次调用 showAlternativeBillingOnlyInformationDialog 向用户显示对话框。对于其他响应代码,请参阅响应处理部分。
向 Google Play 报告交易
通过备用结算系统进行的所有交易必须在 24 小时内从您的后端调用 Google Play Developer API 报告给 Google Play,并提供通过以下 API 获得的 externalTransactionToken
。对于每次一次性购买、每个新订阅以及现有订阅的任何升级/降级,都应生成一个新的 externalTransactionToken。要了解如何在获得 externalTransactionToken
后报告交易,请参阅后端集成指南。
Kotlin
billingClient.createAlternativeBillingOnlyReportingDetailsAsync(object:
AlternativeBillingOnlyReportingDetailsListener {
override fun onAlternativeBillingOnlyTokenResponse(
billingResult: BillingResult,
alternativeBillingOnlyReportingDetails:
AlternativeBillingOnlyReportingDetails?) {
if (billingResult.responseCode != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors.
return
}
val externalTransactionToken =
alternativeBillingOnlyReportingDetails?
.externalTransactionToken
// Send transaction token to backend and report to Google Play.
}
});
Java
billingClient.createAlternativeBillingOnlyReportingDetailsAsync(
new AlternativeBillingOnlyReportingDetailsListener() {
@Override
public void onAlternativeBillingOnlyTokenResponse(
BillingResult billingResult,
@Nullable AlternativeBillingOnlyReportingDetails
alternativeBillingOnlyReportingDetails) {
if (billingResult.getResponseCode() != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors.
return;
}
String transactionToken =
alternativeBillingOnlyReportingDetails
.getExternalTransactionToken();
// Send transaction token to backend and report to Google Play.
}
});
响应处理
上述方法 isAlternativeBillingOnlyAvailableAsync()、showAlternativeBillingOnlyInformationDialog()
和 createAlternativeBillingOnlyReportingDetailsAsync()
在发生错误时可能会返回非 BillingResponseCode.OK 的响应。建议的错误处理方式如下所述
ERROR
:这是一个内部错误。不要继续进行交易。下次用户尝试购买时,再次调用showAlternativeBillingOnlyInformationDialog()
显示信息对话框进行重试。FEATURE_NOT_SUPPORTED
:当前设备上的 Play 商店不支持备用结算 API。不要继续进行交易。USER_CANCELED
:不要继续进行交易。下次用户尝试购买时,再次调用showAlternativeBillingOnlyInformationDialog()
显示信息对话框。BILLING_UNAVAILABLE
:该交易不符合仅备用结算的条件,因此不应在此计划下进行。这可能是因为用户不在该计划的适用国家/地区,或者您的帐号尚未成功注册该计划。如果是后一种情况,请在 Play 管理中心检查您的注册状态。DEVELOPER_ERROR
:请求出错。在继续之前,使用调试消息识别并纠正错误。NETWORK_ERROR, SERVICE_DISCONNECTED, SERVICE_UNAVAILABLE
:这些是应重试的临时错误。在SERVICE_DISCONNECTED
的情况下,在重试之前重新与 Google Play 建立连接。
测试备用结算
应使用许可测试人员来测试您的备用结算集成。通过许可测试帐号发起的交易将不会向您收取费用。有关如何配置许可测试人员的更多信息,请参阅使用应用许可测试应用内结算功能。
下一步
完成应用内集成后,您可以集成后端。