Hướng dẫn tích hợp trong ứng dụng cho chương trình ưu đãi bên ngoài

Hướng dẫn này mô tả cách tích hợp với các API để hỗ trợ việc chào bán bên ngoài trong các ứng dụng và khu vực đủ điều kiện. Để tìm hiểu thêm về chương trình chào bán bên ngoài bao gồm các điều kiện tham gia và phạm vi địa lý. yêu cầu của chương trình.

Thiết lập Thư viện Play Billing

Để sử dụng API chào bán bên ngoài, thêm phần phụ thuộc Thư viện Play Billing phiên bản 6.2.1 trở lên vào ứng dụng Android của bạn. Nếu bạn cần di chuyển từ một phiên bản cũ, hãy làm theo các hướng dẫn trong hướng dẫn di chuyển trước khi triển khai chào bán bên ngoài.

Kết nối với Google Play

Các bước đầu tiên trong quy trình tích hợp cũng giống như các bước được mô tả trong hướng dẫn tích hợp thanh toán, kèm theo một vài sửa đổi khi khởi chạy BillingClient:

• Bạn cần gọi một phương thức mới để cho biết rằng bạn muốn sử dụng ưu đãi: enableExternalOffer.

Ví dụ sau minh hoạ việc khởi động BillingClient với một số điểm sửa đổi:

var billingClient = BillingClient.newBuilder(context)
  .enableExternalOffer()
  .build()

private BillingClient billingClient = BillingClient.newBuilder(context)
    .enableExternalOffer()
    .build();

Sau khi khởi động BillingClient, bạn cần thiết lập kết nối với Google Play theo mô tả trong hướng dẫn tích hợp.

Kiểm tra tính khả dụng

Ứng dụng của bạn nên xác nhận rằng ưu đãi bên ngoài là có sẵn bằng cách gọi điện isExternalOfferAvailableAsync.

API này trả về BillingResponseCode.OK nếu có ưu đãi bên ngoài. Xem bài viết xử lý phản hồi để biết thông tin chi tiết về cách ứng dụng của bạn phản hồi các mã phản hồi khác.

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.
})

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.
      }

});

Chuẩn bị mã thông báo giao dịch bên ngoài

Để báo cáo giao dịch bên ngoài cho Google Play, bạn phải có mã giao dịch được tạo từ Thư viện Play Billing. Trang bên ngoài mới mã thông báo giao dịch phải được tạo mỗi khi người dùng truy cập vào một trang web của bạn thông qua API chào bán bên ngoài. Bạn có thể thực hiện việc này bằng cách gọi createExternalOfferReportingDetailsAsync. Mã thông báo này phải là được tạo ngay trước khi người dùng được chuyển ra ngoài ứng dụng. Phải không bao giờ được lưu vào bộ nhớ đệm và tạo một mã mới mỗi khi người dùng được chuyển hướng bên ngoài ứng dụng.

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.
    }
})

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.
      }
});

Hộp thoại thông tin dành cho người dùng

Để tích hợp với ưu đãi bên ngoài, ứng dụng đủ điều kiện của bạn phải hiển thị thông tin màn hình giúp người dùng hiểu rằng họ sắp được chuyển hướng ra ngoài ứng dụng đến một trang web bên ngoài. Màn hình thông tin phải được hiển thị cho người dùng bằng gọi API showExternalOfferInformationDialog trước khi liên kết với một nội dung chào bán bên ngoài.

// 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)

// 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);

Nếu phương thức này trả về BillingResponseCode.OK, thì ứng dụng của bạn có thể tiếp tục đưa người dùng đến trang web bên ngoài. Nếu phương thức này trả về BillingResponseCode.USER_CANCELED, ứng dụng của bạn không được tiếp tục mở của bạn.

Báo cáo giao dịch cho Google Play

Tất cả giao dịch bên ngoài đều phải được báo cáo cho Google Play bằng cách gọi API Nhà phát triển Google Play từ phần phụ trợ. Giao dịch bên ngoài phải được báo cáo trong khi cung cấp externalTransactionToken có được bằng cách sử dụng API createExternalOfferReportingDetailsAsync. Nếu người dùng thực hiện nhiều các giao dịch mua hàng, bạn có thể sử dụng cùng một externalTransactionToken để báo cáo từng giao dịch mua. Để tìm hiểu cách báo cáo giao dịch, hãy xem hướng dẫn tích hợp phần phụ trợ.

Xử lý phản hồi

Khi xảy ra lỗi, các phương thức isExternalOfferAvailableAsync, createExternalOfferReportingDetailsAsync và showExternalOfferInformationDialog có thể trả về các phản hồi 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 showExternalOfferInformationDialog() để hiển thị thông tin cho người dùng vào lần tiếp theo bạn cố gắng hướng người dùng ra ngoài .
• FEATURE_NOT_SUPPORTED: API chào bán bên ngoài không được hỗ trợ bởi Cửa hàng Play 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 điện showExternalOfferInformationDialog() một lần nữa để hiển thị thông tin cho người dùng vào lần tiếp theo bạn cố gắng hướng người dùng ra ngoài ứng dụng.
• BILLING_UNAVAILABLE: Giao dịch không đủ điều kiện cho ưu đãi bên ngoài và do đó không nên tiếp tục theo chương trình này. Điều này là do 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 có, 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à lỗi tạm thời cần được xử lý bằng chính sách thử lại thích hợp. Trong trường hợp SERVICE_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 ưu đãi bên ngoài

Bạn nên sử dụng nhân viên kiểm thử được cấp phép để kiểm thử việc tích hợp chào bán bên ngoài. Bạn sẽ không được lập hoá đơn cho các giao dịch do người kiểm thử được cấp phép tài khoản. Xem bài viết Thử 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 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ợ.