เอกสารนี้อธิบายวิธีผสานรวม Play Billing Library API เพื่อเสนอลิงก์เนื้อหาภายนอกในแอปที่มีสิทธิ์ ซึ่งรวมถึงความสามารถในการลิงก์ผู้ใช้ในสหรัฐอเมริกาออกไปนอกแอป Play เพื่อเสนอเนื้อหาดิจิทัลที่ซื้อในแอปและการดาวน์โหลดแอปแก่ผู้ใช้ ดูข้อมูลเพิ่มเติมเกี่ยวกับโปรแกรมนี้ได้ที่ ข้อกำหนดของโปรแกรม
การตั้งค่า Play Billing Library
เพิ่มทรัพยากร Dependency ของ Play Billing Library ลงในแอป Android หากต้องการใช้ ลิงก์ภายนอก API คุณต้องใช้เวอร์ชัน 8.2.1 ขึ้นไป หากต้องการ ย้ายข้อมูลจากเวอร์ชันก่อนหน้า ให้ทำตามวิธีการใน คู่มือการย้ายข้อมูลก่อนเพิ่มลิงก์เนื้อหาภายนอก
เริ่มต้นไคลเอ็นต์การเรียกเก็บเงิน
หากต้องการเริ่มต้นไคลเอ็นต์การเรียกเก็บเงิน ให้ทำตามขั้นตอนเดียวกับที่อธิบายไว้ใน
หัวข้อเริ่มต้น BillingClient โดยมีการแก้ไขดังนี้
- อย่าเปิดใช้
PurchasesUpdatedListener\- ไม่จำเป็นต้องใช้ Listener นี้ สำหรับลิงก์เนื้อหาภายนอก - เรียก
enableBillingProgram()ด้วยBillingProgram.EXTERNAL_CONTENT_LINKเพื่อระบุว่าแอปของคุณใช้ลิงก์เนื้อหาภายนอก
ตัวอย่างต่อไปนี้แสดงการเริ่มต้น BillingClient ด้วยการแก้ไขเหล่านี้
Kotlin
val billingClient = BillingClient.newBuilder(context) .enableBillingProgram( EnableBillingProgramParams.newBuilder() .setBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK) .build() ) .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( billingResult: BillingResult, billingProgramAvailabilityDetails: BillingProgramAvailabilityDetails ) { 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 Coroutines เพื่อไม่ให้ต้องกำหนด Listener แยกต่างหาก
เตรียมโทเค็นธุรกรรมภายนอก
จากนั้นคุณต้องสร้างโทเค็นธุรกรรมภายนอกจาก Play Billing Library คุณต้องสร้างโทเค็นธุรกรรมภายนอกใหม่ทุกครั้งที่ผู้ใช้เข้าชมเว็บไซต์ภายนอกผ่าน External Links 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 Coroutines เพื่อไม่ให้ต้องกำหนด 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: Play Store ในอุปกรณ์ปัจจุบันไม่รองรับ External Content Link API อย่าดำเนินการธุรกรรมต่อหรือเปิดเว็บไซต์ภายนอกUSER_CANCELED: อย่าดำเนินการเปิดเว็บไซต์ภายนอกต่อ เรียกใช้launchExternalLink()อีกครั้งในครั้งถัดไปที่คุณพยายามนำผู้ใช้ออกไปนอกแอปBILLING_UNAVAILABLE: ธุรกรรมไม่มีสิทธิ์ใช้ลิงก์เนื้อหาภายนอก ดังนั้นอย่าดำเนินการต่อภายใต้โปรแกรมนี้ เนื่องจากผู้ใช้ไม่ได้อยู่ในประเทศที่มีสิทธิ์เข้าร่วมโปรแกรมนี้ หรือบัญชีของคุณไม่ได้ลงทะเบียนเข้าร่วมโปรแกรมนี้เรียบร้อยแล้ว หากเป็นกรณีหลัง ให้ตรวจสอบสถานะการลงทะเบียนใน Play Developer ConsoleDEVELOPER_ERROR: เกิดข้อผิดพลาดกับคำขอ ใช้ข้อความดีบักเพื่อระบุและแก้ไขข้อผิดพลาดก่อนดำเนินการต่อNETWORK_ERROR, SERVICE_DISCONNECTED, SERVICE_UNAVAILABLE: ข้อผิดพลาดชั่วคราวที่ควรจัดการด้วยนโยบายการลองใหม่ที่เหมาะสม ในกรณีที่เกิดSERVICE_DISCONNECTEDให้สร้างการเชื่อมต่อกับ Google Play อีกครั้งก่อนที่จะลองอีกครั้ง
ทดสอบลิงก์เนื้อหาภายนอก
คุณควรใช้ผู้ทดสอบใบอนุญาตเพื่อทดสอบการผสานรวมข้อเสนอภายนอก ระบบจะไม่เรียกเก็บเงินจากคุณสำหรับธุรกรรมที่บัญชีผู้ทดสอบใบอนุญาตเป็นผู้เริ่ม ดูข้อมูลเพิ่มเติมเกี่ยวกับการกำหนดค่าผู้ทดสอบใบอนุญาตได้ที่หัวข้อทดสอบการเรียกเก็บเงินสำหรับการซื้อในแอปด้วยการอนุญาตให้ใช้สิทธิแอปพลิเคชัน
ขั้นตอนถัดไป
หลังจากผสานรวมในแอปเสร็จแล้ว คุณก็พร้อมที่จะ ผสานรวมแบ็กเอนด์