คำแนะนำในการผสานรวมในแอปสำหรับลิงก์เนื้อหาภายนอก

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

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

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

เริ่มต้นไคลเอ็นต์การเรียกเก็บเงิน

หากต้องการเริ่มต้นไคลเอ็นต์สำหรับการเรียกเก็บเงิน ให้ทำตามขั้นตอนเดียวกันกับที่อธิบายไว้ใน เริ่มต้น BillingClient โดยมีการแก้ไขต่อไปนี้

  • อย่าเปิดใช้ PurchasesUpdatedListener - ไม่จำเป็นต้องใช้ Listener นี้ สำหรับลิงก์เนื้อหาภายนอก
  • เรียกใช้ enableBillingProgram() ด้วย BillingProgram.EXTERNAL_CONTENT_LINK เพื่อ ระบุว่าแอปของคุณใช้ลิงก์เนื้อหาภายนอก

ตัวอย่างต่อไปนี้แสดงการเริ่มต้น BillingClient ด้วยการแก้ไขต่อไปนี้

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

เชื่อมต่อกับ Google Play

หลังจากเริ่มต้น BillingClient แล้ว ให้เชื่อมต่อกับ Google Play ตามที่อธิบายไว้ใน เชื่อมต่อกับ Google Play

ตรวจสอบสิทธิ์ของผู้ใช้

หลังจากเชื่อมต่อกับ Google Play แล้ว คุณต้องตรวจสอบว่าผู้ใช้มีสิทธิ์เข้าร่วมโปรแกรม ลิงก์เนื้อหาภายนอกหรือไม่โดยเรียกใช้เมธอด isBillingProgramAvailableAsync() เมธอดนี้จะแสดงผล BillingResponseCode.OK หากผู้ใช้มีสิทธิ์เข้าร่วมโปรแกรม ลิงก์เนื้อหาภายนอก ตัวอย่างต่อไปนี้แสดงวิธีตรวจสอบสิทธิ์ของผู้ใช้สำหรับลิงก์เนื้อหาภายนอก

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

    });

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

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

จากนั้นคุณต้องสร้างโทเค็นธุรกรรมภายนอกจาก Play Billing Library ต้องสร้างโทเค็นธุรกรรมภายนอกใหม่ทุกครั้งที่ผู้ใช้ เข้าชมเว็บไซต์ภายนอกผ่าน API ลิงก์ภายนอก ซึ่งทำได้ด้วยการ เรียกใช้ createBillingProgramReportingDetailsAsync API ควรสร้างโทเค็น ทันทีก่อนที่จะลิงก์ผู้ใช้ออก

หมายเหตุ: คุณไม่ควรแคชโทเค็นธุรกรรมภายนอก และควร สร้างโทเค็นใหม่ทุกครั้งที่ลิงก์ผู้ใช้ออกไป

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

หากใช้ส่วนขยาย Kotlin คุณจะใช้โครูทีน Kotlin ได้โดยไม่ต้องกำหนด Listener แยกต่างหาก

เปิดลิงก์ภายนอก

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

เมื่อเรียกใช้เมธอด launchExternalLink คุณต้องระบุรายละเอียดของลิงก์ภายนอก ผ่าน LaunchExternalLinkParams คลาสนี้มีพารามิเตอร์ต่อไปนี้

  • URI ของลิงก์ - ลิงก์ไปยังเว็บไซต์ภายนอกที่มีการเสนอเนื้อหาดิจิทัลหรือ การดาวน์โหลดแอป สำหรับการดาวน์โหลดแอป คุณต้องลงทะเบียนและ อนุมัติลิงก์นี้ใน Play Developer Console
  • ประเภทลิงก์ - ประเภทเนื้อหาที่เสนอต่อผู้ใช้
  • โหมดเปิดใช้งาน - ระบุวิธีเปิดลิงก์ สำหรับการดาวน์โหลดแอป คุณต้องตั้งค่านี้เป็น LAUNCH_IN_EXTERNAL_BROWSER_OR_APP
  • โปรแกรมการเรียกเก็บเงิน - ตั้งค่าเป็น 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);

การจัดการคำตอบ

เมื่อเกิดข้อผิดพลาด เมธอด isBillingProgramAvailableAsync() และ createBillingProgramReportingDetailsAsync() และ onLaunchExternalLinkResponse() อาจให้ BillingResponseCode อื่น ที่ไม่ใช่ BillingResponseCode.OK พิจารณาจัดการรหัสการตอบกลับเหล่านี้ดังนี้

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

ทดสอบลิงก์เนื้อหาภายนอก

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

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

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