ย้ายข้อมูลไปยัง 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.1.0"
     implementation "com.android.billingclient:billing:$billing_version"
   }
   

   หากคุณใช้ Kotlin โมดูล Google Play Billing Library KTX จะมีส่วนขยาย Kotlin และการรองรับ Coroutines ซึ่งช่วยให้คุณเขียน 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 ที่นำออกและ API ทางเลือกที่เกี่ยวข้องซึ่งคุณต้องใช้ในแอป

   อัปเกรดจาก

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

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

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

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