מיגרציה לגרסה 9 של ספריית החיובים ב-Google Play מגרסה 7 או 8

במאמר הזה מוסבר איך לעבור מספריית החיובים ב-Google Play‏ (PBL) בגרסה 7 או 8 לגרסה 9, ואיך לשלב את התכונות החדשות.

רשימת השינויים המלאה בגרסה 9.0.0 מפורטת בנתוני הגרסה.

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

Help me upgrade my Play Billing Library implementation.

סקירה כללית

גרסה 9 של PBL כוללת שיפורים בממשקי API קיימים, וגם הסרה של ממשקי API שהוצאו משימוש בעבר. בגרסה הזו של הספרייה יש גם הקשר עשיר יותר לשגיאות באמצעות קודי תגובות משנה חדשים.

תאימות לדורות קודמים לשדרוג של PBL

כדי לעבור ל-PBL 9, אתם צריכים לעדכן או להסיר חלק מההפניות הקיימות ל-API מהאפליקציה, כמו שמתואר בנתוני הגרסה ובהמשך המדריך הזה להעברת נתונים.

שדרוג מ-PBL 7 או 8 ל-PBL 9

כדי לשדרג מ-PBL 7 או 8 ל-PBL 9, מבצעים את השלבים הבאים:

1. מעדכנים את גרסת התלות של ספריית החיובים ב-Play בקובץ build.gradle של האפליקציה.

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

   אם אתם משתמשים ב-Kotlin, מודול KTX של ספריית החיובים ב-Google Play מכיל תוספים של Kotlin ותמיכה בשגרות המשך (coroutines) שמאפשרים לכם לכתוב ב-Kotlin אידיומטי כשאתם משתמשים בספריית החיובים ב-Google Play. כדי לכלול את התוספים האלה בפרויקט, מוסיפים את התלות הבאה לקובץ 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 חלופי לשימוש
   ממשקי API של queryPurchaseHistoryAsync	מידע נוסף זמין במאמר שאילתה על היסטוריית הרכישות. אם השתמשתם ב-queryPurchaseHistoryAsync כדי לקבוע זכאות לתקופות ניסיון בחינם, עכשיו אתם צריכים להשתמש ב-ProductDetails.getSubscriptionOfferDetails()‎ כדי לקבוע לאילו מבצעים המשתמש זכאי.
   BillingClient.SkuType	BillingClient.ProductType. הקבועים של סוגי המוצרים INAPP ו-SUBS נשארים דומים מבחינה פונקציונלית לקבועים של סוגי המק"טים שהוצאו משימוש.
   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 נשארים דומים מבחינה פונקציונלית לקבועים של סוגי המק"טים שהוצאו משימוש.
   SkuDetails	ProductDetails. זהו מודל הנתונים החדש שתומך במוצרים בחיוב חד-פעמי.
   SkuDetailsParams	משתמשים ב-QueryProductDetailsParams עם queryProductDetailsAsync.
   SkuDetailsResponseListener	משתמשים ב-ProductDetailsResponseListener עם queryProductDetailsAsync.
   QueryPurchaseHistoryParams	משתמשים ב-queryProductDetailsAsync לרכישות פעילות או ממתינות. עוקבים אחרי רכישות שנוצלו בשרתי בק-אנד. משתמשים ב-Voided Purchases API בצד השרת לרכישות שבוטלו או שהן לא חוקיות.
   getSkuDetailsList ו-setSkuDetailsList	משתמשים ב-BillingFlowParams.Builder.setProductDetailsParamsList

4. (מומלץ) להפעיל חיבור מחדש אוטומטי לשירות.

   אם מתבצעת קריאה ל-API כשהשירות מנותק, ספריית החיובים ב-Play יכולה לנסות ליצור מחדש את החיבור לשירות באופן אוטומטי. איך מפעילים את החיבור מחדש האוטומטי לשירות

5. טיפול בקודי תגובות משנה חדשים.

   האובייקט BillingResult שמוחזר מ-launchBillingFlow() יכלול עכשיו שדה של קוד תגובת משנה. השדה הזה יאוכלס רק במקרים מסוימים, כדי לספק סיבה ספציפית יותר לכישלון. השדה של תגובת המשנה יכול לכלול את הערכים הבאים:

   • ‫PAYMENT_DECLINED_DUE_TO_INSUFFICIENT_FUNDS – מוחזר כשהסכום שיש למשתמש קטן ממחיר הפריט שהוא מנסה לרכוש.
   • ‫USER_INELIGIBLE – מוחזר כשהמשתמש לא עומד בדרישות הסף שהוגדרו למבצע על מינוי.
   • ‫NO_APPLICABLE_SUB_RESPONSE_CODE – ערך ברירת המחדל, שמוחזר כשאין קוד תגובת משנה רלוונטי אחר.

   שלב ההעברה: כדי לספק חוויית משתמש טובה יותר, צריך לעדכן את PurchasesUpdatedListener או את הטיפול המקביל בתוצאות כך שיזהו את קודי המשנה הספציפיים האלה בתגובה ויגיבו להם. לדוגמה, בקשה לתקן את אמצעי התשלום או הצגת הודעת שגיאה ספציפית.

6. מודעות לסיווג מחדש של קודי שגיאה.

   במקרים שבהם האפליקציה של חנות Play חסומה על ידי המערכת (לדוגמה, במצב מתאים לילדים של OEM), קוד התגובה מ-PBL השתנה מ-ERROR ל-BILLING_UNAVAILABLE.

   שלב בהעברה: ודאו שהלוגיקה של הטיפול בשגיאות מתאימה לשינוי הזה, ולא מסתמכת על קבלת שגיאה כללית בתרחישים הספציפיים האלה.

7. מטפלים בערכי null של DeveloperProvidedBillingDetails.getLinkUri().

   אם אתם משתמשים ב-DeveloperProvidedBillingDetails כחלק משילוב של תשלומים חיצוניים, getLinkUri() הוא עכשיו @Nullable.

   שלב ההעברה: כדי לטפל בשינוי הזה בצורה בטוחה, ודאו שקוד השילוב מטפל גם בערכים של null וגם בערכים של מחרוזת ריקה ("") מהשיטה DeveloperProvidedBillingDetails.getLinkUri() לפני ניתוח או הפעלה של כוונות דפדפן. לדוגמה:

   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. שינויים אופציונליים.

   • תמיכה ברכישות ממתינות לתוכניות בתשלום מראש. מידע נוסף זמין במאמר טיפול במינויים ובעסקאות בהמתנה.

   • מינויים בתשלומים וירטואליים. מידע נוסף זמין במאמר שילוב מינויים בתשלומים.