ย้ายข้อมูลไปยัง Google Play Billing Library 9 จากเวอร์ชัน 7 หรือ 8

เอกสารนี้อธิบายวิธีย้ายข้อมูลจาก Google Play Billing Library (PBL) 7 หรือ 8 ไปยัง PBL 9 และวิธีผสานรวมกับฟีเจอร์ใหม่

ดูรายการการเปลี่ยนแปลงทั้งหมดในเวอร์ชัน 9.0.0 ได้ในบันทึกประจำรุ่น

ภาพรวม

PBL 9 มีการปรับปรุง API ที่มีอยู่พร้อมกับการนำ API ที่เลิกใช้งานไปก่อนหน้านี้ออก นอกจากนี้ ไลบรารีเวอร์ชันนี้ยังเพิ่มบริบทข้อผิดพลาดที่ละเอียดยิ่งขึ้นผ่านรหัสการตอบกลับย่อยใหม่

ความเข้ากันได้แบบย้อนหลังสำหรับการอัปเกรด PBL

หากต้องการย้ายข้อมูลไปยัง PBL 9 คุณต้องอัปเดตหรือนำการอ้างอิง API ที่มีอยู่บางรายการออกจากแอปตามที่อธิบายไว้ในหมายเหตุประจำรุ่นและในภายหลัง ในคำแนะนำในการย้ายข้อมูลนี้

อัปเกรดจาก PBL 7 หรือ 8 เป็น PBL 9

หากต้องการอัปเกรดจาก PBL 7 หรือ 8 เป็น PBL 9 ให้ทำตามขั้นตอนต่อไปนี้

1. อัปเดตเวอร์ชันทรัพยากร Dependency ของ Play Billing Library ในไฟล์ build.gradleของแอป

   dependencies {
     def billing_version = "9.0.0"
     implementation "com.android.billingclient:billing:$billing_version"
   }
   

   หากคุณใช้ Kotlin โมดูล KTX ของ Google Play Billing Library จะมีส่วนขยาย Kotlin และการรองรับ Coroutine ที่ช่วยให้คุณเขียน Kotlin ที่เป็นสำนวนเมื่อใช้ Google Play Billing Library ได้ หากต้องการรวมส่วนขยายเหล่านี้ไว้ในโปรเจ็กต์ ให้เพิ่มทรัพยากร Dependency ต่อไปนี้ลงในไฟล์ build.gradle ของแอปตามที่แสดง

   dependencies {
     val billing_version = "9.0.0"
     implementation("com.android.billingclient:billing-ktx:$billing_version")
   }
   

2. (ใช้ได้กับการอัปเกรดจาก PBL 7 เป็น PBL 9 เท่านั้น) อัปเดตการใช้งานเมธอด queryProductDetailsAsync

   มีการเปลี่ยนแปลงลายเซ็นของเมธอด ProductDetailsResponseListener.onProductDetailsResponse ซึ่ง ต้องมีการเปลี่ยนแปลงในแอปของคุณสำหรับการติดตั้งใช้งาน queryProductDetailsAsync ดูข้อมูลเพิ่มเติมได้ที่แสดงผลิตภัณฑ์ที่พร้อมจำหน่าย

3. จัดการ API ที่ถูกนำออก

   ตารางต่อไปนี้แสดงรายการ API ที่ถูกนำออกและ API ทางเลือกที่เกี่ยวข้องซึ่งคุณต้องใช้ในแอป

   อัปเกรด จาก

   PBL 9 ไม่รองรับ API ที่แสดงในตารางต่อไปนี้อีกต่อไป หากการติดตั้งใช้งานของคุณใช้ API ที่ถูกนำออกไปเหล่านี้ โปรดดูตารางเพื่อหา API ทางเลือกที่เกี่ยวข้อง

   นำ API ที่เลิกใช้งานไปก่อนหน้านี้ออกแล้ว	API สำรองที่จะใช้
   queryPurchaseHistoryAsync API	ดูค้นหาประวัติการซื้อ หากเคยใช้ queryPurchaseHistoryAsync เพื่อพิจารณาสิทธิ์รับช่วงทดลองใช้ฟรี ตอนนี้คุณควรใช้ ProductDetails.getSubscriptionOfferDetails() เพื่อพิจารณาว่าผู้ใช้มีสิทธิ์รับข้อเสนอใด
   BillingClient.SkuType	BillingClient.ProductType ค่าคงที่ประเภทสินค้า INAPP และ SUBS ยังคงมีฟังก์ชันการทำงานคล้ายกับค่าคงที่ประเภท SKU ที่เลิกใช้งานแล้ว
   SkuDetails	ProductDetails นี่คือ โมเดลข้อมูลใหม่ที่รองรับผลิตภัณฑ์แบบเรียกเก็บเงินครั้งเดียว
   SkuDetailsParams	ใช้ QueryProductDetailsParams กับ queryProductDetailsAsync
   SkuDetailsResponseListener	ใช้ ProductDetailsResponseListener กับ queryProductDetailsAsync
   QueryPurchaseHistoryParams	ใช้ queryPurchasesAsync สำหรับการซื้อที่ใช้งานอยู่หรือรอดำเนินการ ติดตามการซื้อที่ใช้แล้วในเซิร์ฟเวอร์แบ็กเอนด์ ใช้ Voided Purchases API ฝั่งเซิร์ฟเวอร์สำหรับการซื้อที่ยกเลิกหรือเป็นโมฆะ
   getSkuDetailsList และ setSkuDetailsList	ใช้ BillingFlowParams.Builder.setProductDetailsParamsList
   querySkuDetailsAsync	queryProductDetailsAsync
   enablePendingPurchases() (API ที่ไม่มีพารามิเตอร์)	enablePendingPurchases(PendingPurchasesParams params) โปรดทราบว่า enablePendingPurchases() ที่เลิกใช้งานแล้วมีฟังก์ชันการทำงานเทียบเท่ากับ enablePendingPurchases(PendingPurchasesParams.newBuilder().enableOneTimeProducts().build())
   queryPurchasesAsync(String skuType, PurchasesResponseListener listener)	queryPurchasesAsync

   อัปเกรด จาก

   ตารางต่อไปนี้แสดงรายการ API ที่ถูกนำออกใน PBL 9 และ API ทางเลือกที่เกี่ยวข้องซึ่งคุณต้องใช้ในแอป

   นำ API ที่เลิกใช้งานไปก่อนหน้านี้ออกแล้ว	API สำรองที่จะใช้
   BillingClient.SkuType	BillingClient.ProductType ค่าคงที่ประเภทสินค้า INAPP และ SUBS ยังคงมีฟังก์ชันการทำงานคล้ายกับค่าคงที่ประเภท SKU ที่เลิกใช้งานแล้ว
   SkuDetails	ProductDetails นี่คือ โมเดลข้อมูลใหม่ที่รองรับผลิตภัณฑ์แบบเรียกเก็บเงินครั้งเดียว
   SkuDetailsParams	ใช้ QueryProductDetailsParams กับ queryProductDetailsAsync
   SkuDetailsResponseListener	ใช้ ProductDetailsResponseListener กับ queryProductDetailsAsync
   QueryPurchaseHistoryParams	ใช้ queryProductDetailsAsync สำหรับการซื้อที่ใช้งานอยู่หรือรอดำเนินการ ติดตามการซื้อที่ใช้แล้วในเซิร์ฟเวอร์แบ็กเอนด์ ใช้ Voided Purchases API ฝั่งเซิร์ฟเวอร์สำหรับการซื้อที่ยกเลิกหรือเป็นโมฆะ
   getSkuDetailsList และ setSkuDetailsList	ใช้ BillingFlowParams.Builder.setProductDetailsParamsList

4. (แนะนำ) เปิดใช้การเชื่อมต่อบริการอีกครั้งโดยอัตโนมัติ

   Play Billing Library สามารถพยายามสร้างการเชื่อมต่อบริการใหม่โดยอัตโนมัติ หากมีการเรียก API ขณะที่บริการ ถูกตัดการเชื่อมต่อ ดูข้อมูลเพิ่มเติมได้ที่หัวข้อเปิดใช้การเชื่อมต่อบริการอีกครั้งโดยอัตโนมัติ

5. จัดการรหัสการตอบกลับย่อยใหม่

   ตอนนี้ BillingResult ที่ส่งคืนจาก launchBillingFlow() จะมี ฟิลด์รหัสการตอบกลับย่อย ระบบจะป้อนข้อมูลในช่องนี้ในบางกรณีเท่านั้นเพื่อระบุเหตุผลที่เฉพาะเจาะจงมากขึ้นว่าทำไมจึงไม่สำเร็จ ฟิลด์การตอบกลับย่อย อาจมีค่าต่อไปนี้

   • PAYMENT_DECLINED_DUE_TO_INSUFFICIENT_FUNDS - แสดงเมื่อยอดเงินของผู้ใช้ น้อยกว่าราคาของสินค้าที่ผู้ใช้พยายาม ซื้อ
   • USER_INELIGIBLE - แสดงผลเมื่อผู้ใช้ไม่เป็นไปตามข้อกำหนดด้านการมีสิทธิ์ที่กำหนดค่าไว้สำหรับข้อเสนอการสมัครใช้บริการ
   • NO_APPLICABLE_SUB_RESPONSE_CODE - ค่าเริ่มต้นที่แสดงเมื่อไม่มีรหัสการตอบกลับย่อยอื่นๆ ที่เกี่ยวข้อง

   ขั้นตอนการย้ายข้อมูล: อัปเดต PurchasesUpdatedListener หรือการจัดการผลลัพธ์ที่เทียบเท่าเพื่อจดจำและตอบสนองต่อรหัสการตอบกลับย่อยที่เฉพาะเจาะจงเหล่านี้ เพื่อมอบประสบการณ์ของผู้ใช้ที่ดียิ่งขึ้น เช่น แจ้งให้แก้ไขวิธีการชำระเงินหรือแสดงข้อความแสดงข้อผิดพลาดที่เฉพาะเจาะจง

6. การรับรู้การจัดประเภทรหัสข้อผิดพลาดใหม่

   ในกรณีที่ระบบบล็อกแอป Play Store (เช่น ในโหมดสำหรับเด็กที่ OEM ปรับแต่ง) โค้ดตอบกลับจาก PBL จะเปลี่ยนจาก ERROR เป็น BILLING_UNAVAILABLE

   ขั้นตอนการย้ายข้อมูล: ตรวจสอบว่าตรรกะการจัดการข้อผิดพลาดรองรับการเปลี่ยนแปลงนี้ และไม่ได้อาศัยการได้รับข้อผิดพลาดทั่วไปในสถานการณ์เฉพาะเหล่านี้

7. จัดการความสามารถในการเว้นว่างของ DeveloperProvidedBillingDetails.getLinkUri()

   หากคุณใช้ DeveloperProvidedBillingDetails เป็นส่วนหนึ่งของการผสานรวมการชำระเงินภายนอก ตอนนี้ getLinkUri() คือ @Nullable

   ขั้นตอนการย้ายข้อมูล: เพื่อจัดการการเปลี่ยนแปลงนี้อย่างปลอดภัย โปรดตรวจสอบว่าโค้ดการผสานรวมของคุณจัดการทั้งค่า null และค่าสตริงว่าง ("") จากเมธอด DeveloperProvidedBillingDetails.getLinkUri() ก่อนที่จะแยกวิเคราะห์ หรือเปิดใช้ Intent ของเบราว์เซอร์ เช่น

   Kotlin

   val linkUri = details.getLinkUri()
   if (!linkUri.isNullOrEmpty()) {
     val intent = Intent(Intent.ACTION_VIEW, Uri.parse(linkUri))
     context.startActivity(intent)
   }
   

   Java

   String linkUri = details.getLinkUri();
   if (!android.text.TextUtils.isEmpty(linkUri)) {
     Intent intent = new Intent(Intent.ACTION_VIEW, Uri.parse(linkUri));
     context.startActivity(intent);
   }
   

8. การเปลี่ยนแปลงที่ไม่บังคับ

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

   • การสมัครใช้บริการการผ่อนชำระแบบเสมือนจริง ดูข้อมูลเพิ่มเติมได้ที่การผสานรวมการสมัครใช้บริการแบบผ่อนชำระ