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

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

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

סקירה כללית

גרסה 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

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