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

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

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

ทักษะ Android

ดูใน GitHub

อัปเกรด Play Billing Library

ใช้ทักษะ Android ของ Play Billing Library เพื่ออัปเกรดเป็นเวอร์ชันล่าสุดโดยอัตโนมัติ

หากต้องการติดตั้งทักษะจาก Android CLI ให้เรียกใช้คำสั่งต่อไปนี้

android skills add play-billing-library-version-upgrade

หากต้องการเปิดใช้งานทักษะ ให้ลองใช้พรอมต์ต่อไปนี้

Help me upgrade my Play Billing Library implementation.

ภาพรวม

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.1.0"
     implementation "com.android.billingclient:billing:$billing_version"
   }
   

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

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

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

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

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

   เคล็ดลับ: หากต้องการจัดการ API ที่ถูกนำออก คุณสามารถใช้ Play Billing Library Version Upgrade Skill ทักษะนี้ได้รับการปรับแต่งเพื่อปรับปรุงการย้ายข้อมูลจากรูปแบบที่เลิกใช้แล้วไปยังมาตรฐาน PBL ล่าสุด ทักษะนี้จะตรวจหาการเรียกใช้เมธอดที่ล้าสมัยโดยอัตโนมัติ และให้คำแนะนำที่แม่นยำสำหรับการอัปเดตการติดตั้งใช้งานให้เป็นไปตามมาตรฐานล่าสุด

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

   อัปเกรดจาก

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

   นำ API ที่เลิกใช้งานก่อนหน้านี้ออกแล้ว	API สำรองที่ใช้ได้
   API ของ queryPurchaseHistoryAsync	ดูการค้นหาประวัติการซื้อ หากคุณใช้ 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

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

   หมายเหตุ: คุณต้องใช้ไลบรารี AndroidX.core เวอร์ชัน 1.9 ขึ้นไปเพื่อให้ฟีเจอร์นี้ทำงานได้

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

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

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

   Kotlin

   val linkUri = details.linkUri
   if (!linkUri.isNullOrEmpty()) {
       val intent = Intent(Intent.ACTION_VIEW, linkUri.toUri())
       context.startActivity(intent)
   }
   MigrateGpblv9.kt

   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. การเปลี่ยนแปลงที่ไม่บังคับ

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

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