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

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

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

סקירה כללית

‫PBL 9 כולל שיפורים בממשקי 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 חלופי לשימוש
   queryPurchaseHistoryAsync APIs	איך בודקים את היסטוריית הרכישות אם השתמשתם ב-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 חסומה על ידי המערכת (למשל, במצב ילדים שמותאם אישית על ידי יצרן ציוד מקורי), קוד התגובה מ-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. שינויים אופציונליים.

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

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