เอกสารนี้อธิบายวิธีผสานรวม 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 ConsoleDEVELOPER_ERROR: คำขอมีข้อผิดพลาด ใช้ข้อความแก้ไขข้อบกพร่อง เพื่อระบุและแก้ไขข้อผิดพลาดก่อนดำเนินการต่อNETWORK_ERROR, SERVICE_DISCONNECTED, SERVICE_UNAVAILABLE: ข้อผิดพลาดเหล่านี้เป็นข้อผิดพลาดชั่วคราวที่ควรจัดการด้วยนโยบายลองอีกครั้งที่เหมาะสม ในกรณีของSERVICE_DISCONNECTEDให้สร้างการเชื่อมต่อกับ Google Play อีกครั้งก่อนที่จะลองอีกครั้ง
ทดสอบลิงก์เนื้อหาภายนอก
คุณควรใช้ผู้ทดสอบใบอนุญาตเพื่อทดสอบการผสานรวมข้อเสนอภายนอก ระบบจะไม่เรียกเก็บเงินจากคุณสำหรับธุรกรรมที่บัญชีผู้ทดสอบใบอนุญาตเริ่ม ดูข้อมูลเพิ่มเติมเกี่ยวกับการกำหนดค่าผู้ทดสอบใบอนุญาตได้ที่ทดสอบการเรียกเก็บเงินสำหรับการซื้อในแอปด้วยการอนุญาตให้ใช้สิทธิแอปพลิเคชัน
ขั้นตอนถัดไป
หลังจากผสานรวมในแอปเสร็จแล้ว คุณก็พร้อมที่จะผสานรวมแบ็กเอนด์