Tài liệu này mô tả cách tích hợp các API Thư viện Google Play Billing để cung cấp đường liên kết đến nội dung bên ngoài trong các ứng dụng đủ điều kiện. Trong đó có khả năng liên kết người dùng ở Hoa Kỳ ra bên ngoài ứng dụng của bạn trên Play để cung cấp cho người dùng ưu đãi về nội dung kỹ thuật số trong ứng dụng và lượt tải ứng dụng xuống. Để tìm hiểu thêm về chương trình này, hãy xem các yêu cầu của chương trình.
Thiết lập Thư viện Play Billing
Thêm phần phụ thuộc Thư viện Play Billing vào ứng dụng Android của bạn. Để sử dụng các API đường liên kết bên ngoài, bạn cần sử dụng phiên bản 8.2 trở lên. Nếu bạn cần di chuyển từ phiên bản cũ sang, hãy làm theo hướng dẫn trong hướng dẫn di chuyển trước khi thêm đường liên kết đến nội dung bên ngoài.
Khởi động ứng dụng thanh toán
Để khởi động ứng dụng thanh toán, hãy làm theo các bước tương tự như mô tả trong phần Khởi động BillingClient với các điểm sửa đổi sau:
- Đừng bật
PurchasesUpdatedListener– bạn không cần trình nghe này cho đường liên kết đến nội dung bên ngoài. - Gọi
enableBillingProgram()bằngBillingProgram.EXTERNAL_CONTENT_LINKđể cho biết ứng dụng của bạn sử dụng đường liên kết đến nội dung bên ngoài.
Ví dụ sau đây minh hoạ việc khởi động BillingClient với một số điểm sửa đổi:
Kotlin
val billingClient = BillingClient.newBuilder(context)
.enableBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
.build()
Java
private BillingClient billingClient = BillingClient.newBuilder(context)
.enableBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
.build();
Kết nối với Google Play
Sau khi khởi động BillingClient, hãy kết nối với Google Play theo mô tả trong phần Kết nối với Google Play.
Kiểm tra điều kiện của người dùng
Sau khi kết nối với Google Play, bạn phải kiểm tra xem người dùng có đủ điều kiện tham gia chương trình đường liên kết đến nội dung bên ngoài hay không bằng cách gọi phương thức isBillingProgramAvailableAsync(). Phương thức này trả về BillingResponseCode.OK nếu người dùng đủ điều kiện tham gia chương trình đường liên kết đến nội dung bên ngoài. Mẫu sau đây cho biết cách kiểm tra xem người dùng có đủ điều kiện sử dụng đường liên kết đến nội dung bên ngoài hay không:
Kotlin
billingClient.isBillingProgramAvailableAsync(
BillingProgram.EXTERNAL_CONTENT_LINK,
object : BillingProgramAvailabilityListener {
override fun onBillingProgramAvailabilityResponse(
billingProgram: Int, billingResult: BillingResult) {
if (billingResult.responseCode != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors,
// handling external content links unavailable, etc.
return
}
// External content links are available. Prepare an external
// transaction token.
}
})
Java
billingClient.isBillingProgramAvailableAsync(
BillingProgram.EXTERNAL_CONTENT_LINK,
new BillingProgramAvailabilityListener() {
@Override
public void onBillingProgramAvailabilityResponse(
int billingProgram, BillingResult billingResult) {
if (billingResult.getResponseCode() != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors,
// handling external content links unavailable, etc.
return;
}
// External content links are available. Prepare an external
// transaction token.
}
});
Hãy xem phần xử lý phản hồi để biết thông tin cụ thể về cách ứng dụng của bạn sẽ phản hồi các mã phản hồi khác. Nếu đang sử dụng tiện ích Kotlin, bạn có thể dùng coroutine của Kotlin để không phải xác định một trình nghe riêng biệt.
Chuẩn bị mã thông báo giao dịch bên ngoài
Tiếp theo, bạn phải tạo mã thông báo giao dịch bên ngoài từ Thư viện Google Play Billing. Bạn phải tạo một mã thông báo giao dịch bên ngoài mới mỗi khi người dùng truy cập vào một trang web bên ngoài thông qua API đường liên kết bên ngoài. Bạn có thể thực hiện việc này bằng cách gọi API createBillingProgramReportingDetailsAsync. Mã thông báo phải được tạo ngay trước khi người dùng được liên kết.
Lưu ý: Bạn không bao giờ được lưu mã thông báo giao dịch bên ngoài vào bộ nhớ đệm và bạn nên tạo mã thông báo mới mỗi khi người dùng được liên kết.
Kotlin
val params =
BillingProgramReportingDetailsParams.newBuilder()
.setBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
.build();
billingClient.createBillingProgramReportingDetailsAsync(
params,
object : BillingProgramReportingDetailsListener {
override fun onCreateBillingProgramReportingDetailsResponse(
billingResult: BillingResult,
billingProgramReportingDetails: BillingProgramReportingDetails?) {
if (billingResult.responseCode != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors.
return
}
val externalTransactionToken =
billingProgramReportingDetails?.externalTransactionToken
// Persist the external transaction token locally. Pass it to the
// external website when launchExternalLink is called.
}
})
Java
BillingProgramReportingDetailsParams params =
BillingProgramReportingDetailsParams.newBuilder()
.setBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
.build();
billingClient.createBillingProgramReportingDetailsAsync(
params,
new BillingProgramReportingDetailsListener() {
@Override
public void onCreateBillingProgramReportingDetailsResponse(
BillingResult billingResult,
@Nullable BillingProgramReportingDetails
billingProgramReportingDetails) {
if (billingResult.getResponseCode() != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors.
return;
}
String transactionToken =
billingProgramReportingDetails.getExternalTransactionToken();
// Persist the external transaction token locally. Pass it to the
// external website when launchExternalLink is called.
}
});
Nếu đang sử dụng tiện ích Kotlin, bạn có thể dùng coroutine của Kotlin để không phải xác định một trình nghe riêng biệt.
Khởi chạy đường liên kết bên ngoài
Sau khi mã thông báo giao dịch bên ngoài đã sẵn sàng, người dùng có thể được liên kết ra bên ngoài ứng dụng đến một ưu đãi nội dung kỹ thuật số hoặc lượt tải ứng dụng xuống bằng cách gọi phương thức launchExternalLink. Google Play có thể hiển thị các hộp thoại thông tin bổ sung cho người dùng tuỳ thuộc vào chế độ cài đặt người dùng của họ khi bạn gọi API này.
Khi gọi phương thức launchExternalLink, bạn phải cung cấp thông tin chi tiết về đường liên kết bên ngoài thông qua LaunchExternalLinkParams. Lớp này chứa các tham số sau:
- URI của đường liên kết – Đường liên kết đến trang web bên ngoài nơi cung cấp nội dung kỹ thuật số hoặc bản tải ứng dụng xuống. Đối với lượt tải ứng dụng xuống, bạn phải đăng ký và được phê duyệt đường liên kết này trong Play Console.
- Loại đường liên kết – Loại nội dung được cung cấp cho người dùng.
- Chế độ chạy – Chỉ định cách chạy đường liên kết. Đối với lượt tải ứng dụng xuống, bạn phải đặt giá trị này thành
LAUNCH_IN_EXTERNAL_BROWSER_OR_APP. Chương trình thanh toán – Đặt giá trị này thành
BillingProgram.EXTERNAL_CONTENT_LINK.
Kotlin
val params =
LaunchExternalLinkParams.newBuilder()
.setBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
.setLinkUri(Uri.parse("https://www.myapprovedsite.com"))
.setLinkType(LaunchExternalLinkParams.LinkType.LINK_TO_APP_DOWNLOAD)
.setLaunchMode(
LaunchExternalLinkParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP)
.build()
val listener : LaunchExternalLinkResponseListener =
object : LaunchExternalLinkResponseListener {
override fun onLaunchExternalLinkResponse(
billingResult: BillingResult) {
if (billingResult.responseCode != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors.
return
}
// If Launch Mode was set to LAUNCH_IN_EXTERNAL_BROWSER_OR_APP, the
// user was directed outside of the app by Play. This does not give
// any information on the user's actions during the link out, such
// as if a transaction was completed.
// If Launch Mode was set to CALLER_WILL_LAUNCH_LINK, then your app
// may proceed to direct the user to the external website.
}
}
billingClient.launchExternalLink(activity, params, listener)
Java
LaunchExternalLinkParams params =
LaunchExternalLinkParams.newBuilder()
.setBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
.setLinkUri(Uri.parse("https://www.myapprovedsite.com"))
.setLinkType(LaunchExternalLinkParams.LinkType.LINK_TO_APP_DOWNLOAD)
.setLaunchMode(
LaunchExternalLinkParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP)
.build()
LaunchExternalLinkResponseListener listener =
new LaunchExternalLinkResponseListener() {
@Override
public void onLaunchExternalLinkResponse(BillingResult billingResult) {
if (billingResult.getResponseCode() != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors.
return;
}
// If Launch Mode was set to LAUNCH_IN_EXTERNAL_BROWSER_OR_APP, the
// user was directed outside of the app by Play. This does not give
// any information on the user's actions during the link out, such
// as if a transaction was completed.
// If Launch Mode was set to CALLER_WILL_LAUNCH_LINK, then your app
// may proceed to direct the user to the external website.
}
}
billingClient.launchExternalLink(activity, params, listener);
Xử lý phản hồi
Khi xảy ra lỗi, các phương thức isBillingProgramAvailableAsync(), createBillingProgramReportingDetailsAsync() và onLaunchExternalLinkResponse() có thể cung cấp BillingResponseCode khác với BillingResponseCode.OK. Hãy cân nhắc xử lý các mã phản hồi này như sau:
ERROR: Đây là lỗi nội bộ. Đừng tiếp tục giao dịch hoặc mở trang web bên ngoài. Thử lại bằng cách gọi lại API hoặc bằng cách gọilaunchExternalLink()vào lần tiếp theo bạn cố gắng chuyển hướng người dùng ra ngoài ứng dụng.FEATURE_NOT_SUPPORTED: Cửa hàng Play không hỗ trợ các API đường liên kết đến nội dung bên ngoài trên thiết bị hiện tại. Đừng tiếp tục giao dịch hoặc mở trang web bên ngoài.USER_CANCELED: Không tiếp tục mở trang web bên ngoài. Gọi lạilaunchExternalLink()vào lần tiếp theo bạn cố gắng chuyển hướng người dùng ra ngoài ứng dụng.BILLING_UNAVAILABLE: Giao dịch không đủ điều kiện để liên kết đến nội dung bên ngoài nên sẽ không thực hiện tiếp được theo chương trình này. Lý do là vì người dùng không ở quốc gia đủ điều kiện để tham gia chương trình này, hoặc tài khoản của bạn chưa đăng ký tham gia chương trình. Nếu là vì lý do thứ hai, thì hãy kiểm tra trạng thái đăng ký của bạn trong Play Console.DEVELOPER_ERROR: Yêu cầu này gặp phải lỗi. Hãy sử dụng thông báo gỡ lỗi để xác định và sửa lỗi trước khi tiếp tục.NETWORK_ERROR, SERVICE_DISCONNECTED, SERVICE_UNAVAILABLE: Đây là các lỗi tạm thời và bạn cần xử lý bằng một chính sách thử lại phù hợp. Trong trường hợpSERVICE_DISCONNECTED, hãy thiết lập lại kết nối với Google Play trước khi thử lại.
Thử nghiệm đường liên kết đến nội dung bên ngoài
Bạn nên sử dụng người kiểm thử được cấp phép để kiểm thử việc tích hợp ưu đãi bên ngoài. Bạn sẽ không nhận được hoá đơn cho những giao dịch do tài khoản người kiểm thử được cấp phép thực hiện. Hãy xem phần Kiểm nghiệm tính năng thanh toán trong ứng dụng bằng quy trình cấp phép ứng dụng để biết thêm thông tin về cách định cấu hình nhân viên kiểm thử được cấp phép.
Các bước tiếp theo
Sau khi hoàn tất quy trình tích hợp trong ứng dụng, bạn đã sẵn sàng tích hợp phần phụ trợ.