คำแนะนำการผสานรวมในแอปสำหรับโปรแกรมข้อเสนอภายนอก

คู่มือนี้อธิบายวิธีผสานรวมกับ API เพื่อรองรับข้อเสนอภายนอก ในแอปและภูมิภาคที่มีสิทธิ์ หากต้องการดูข้อมูลเพิ่มเติมเกี่ยวกับโปรแกรมข้อเสนอภายนอก รวมถึงข้อกำหนดของการได้รับสิทธิ์และขอบเขตทางภูมิศาสตร์ ข้อกำหนดของโปรแกรม

การตั้งค่า Play Billing Library

หากต้องการใช้ API ของข้อเสนอภายนอก เพิ่มทรัพยากร Dependency ของ Play Billing Library เวอร์ชัน 6.2.1 ขึ้นไป ไปยังแอป Android ของคุณ หากต้องการย้ายข้อมูลจากเวอร์ชันก่อนหน้า ให้ทำตาม วิธีการในคำแนะนำในการย้ายข้อมูลก่อนที่คุณจะพยายามใช้งาน ข้อเสนอภายนอก

เชื่อมต่อกับ 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.
      }

});

เตรียมโทเค็นธุรกรรมภายนอก

หากต้องการรายงานธุรกรรมภายนอกไปยัง Google Play คุณต้องมี โทเค็นธุรกรรมที่สร้างขึ้นจาก Play Billing Library ผู้ใช้ภายนอกใหม่ ต้องสร้างโทเค็นธุรกรรมทุกครั้งที่ผู้ใช้เข้าชม ผ่าน 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 โดยการเรียกใช้ API สำหรับนักพัฒนาซอฟต์แวร์ Google Play จากแบ็กเอนด์ของคุณ ธุรกรรมภายนอก ต้องรายงานในขณะที่มอบ ได้รับ externalTransactionToken โดยใช้ createExternalOfferReportingDetailsAsync API หากผู้ใช้สร้าง คุณสามารถใช้ externalTransactionToken เพื่อรายงานการซื้อแต่ละรายการ ดูวิธีรายงาน โปรดดูคู่มือการผสานรวมแบ็กเอนด์

การจัดการการตอบกลับ

เมื่อเกิดข้อผิดพลาด เมธอด isExternalOfferAvailableAsync createExternalOfferReportingDetailsAsync และ showExternalOfferInformationDialog อาจแสดงคำตอบอื่นที่ไม่ใช่ BillingResponseCode.OK โปรดพิจารณาจัดการโค้ดตอบกลับเหล่านี้ดังนี้

  • ERROR: นี่เป็นข้อผิดพลาดภายใน ไม่ทำธุรกรรมต่อ หรือ เปิดเว็บไซต์ภายนอก โปรดลองอีกครั้งโดยการโทร showExternalOfferInformationDialog() เพื่อแสดงข้อมูล ในครั้งถัดไปที่คุณพยายามนำผู้ใช้ไปนอก แอป
  • FEATURE_NOT_SUPPORTED: API ของข้อเสนอภายนอกไม่รองรับโดย Play Store ในอุปกรณ์ที่ใช้อยู่ ไม่ทำธุรกรรมต่อ หรือ เปิดเว็บไซต์ภายนอก
  • USER_CANCELED: โปรดอย่าเปิดเว็บไซต์ภายนอก โทร showExternalOfferInformationDialog() อีกครั้งเพื่อแสดงข้อมูล ในครั้งถัดไปที่คุณพยายามนำผู้ใช้ไปนอก แอปนั้น
  • BILLING_UNAVAILABLE: ธุรกรรมนี้ไม่มีสิทธิ์ใช้ข้อเสนอภายนอก และก็ไม่ควรดำเนินการต่อภายใต้โปรแกรมนี้ ซึ่งอาจเป็นเพราะ ผู้ใช้ไม่ได้อยู่ในประเทศที่มีสิทธิ์เข้าร่วมโปรแกรมนี้ หรือบัญชีของคุณมี ยังลงทะเบียนเข้าร่วมโปรแกรมไม่สำเร็จ หากเป็นกรณีหลัง ให้ตรวจสอบ สถานะการลงทะเบียนของคุณใน Play Developer Console
  • DEVELOPER_ERROR: มีข้อผิดพลาดเกี่ยวกับคำขอ ใช้ข้อความแก้ไขข้อบกพร่อง เพื่อระบุและแก้ไขข้อผิดพลาดก่อนดำเนินการต่อ
  • NETWORK_ERROR, SERVICE_DISCONNECTED, SERVICE_UNAVAILABLE: ต่อไปนี้คือ ข้อผิดพลาดชั่วคราวที่ควรจัดการด้วยนโยบายการลองใหม่ที่เหมาะสม ในกรณีของ SERVICE_DISCONNECTED ให้สร้างการเชื่อมต่อกับ Google Play ก่อนที่จะลองอีกครั้ง

ทดสอบข้อเสนอภายนอก

ควรใช้ผู้ทดสอบใบอนุญาตเพื่อทดสอบการผสานรวมข้อเสนอภายนอก คุณ จะไม่มีการออกใบแจ้งหนี้สำหรับธุรกรรมที่ดำเนินการโดยผู้ทดสอบใบอนุญาต บัญชี โปรดดูข้อมูลเพิ่มเติมที่ทดสอบการเรียกเก็บเงินสำหรับการซื้อในแอปด้วยการอนุญาตให้ใช้สิทธิแอปพลิเคชัน ข้อมูลเกี่ยวกับการกำหนดค่าผู้ทดสอบใบอนุญาต

ขั้นตอนถัดไป

เมื่อเสร็จสิ้นการผสานรวมในแอป คุณก็พร้อมที่จะผสานรวม แบ็กเอนด์