מיגרציה לגרסה 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.0.0"
  implementation "com.android.billingclient:billing:$billing_version"
}

    אם אתם משתמשים ב-Kotlin, מודול ה-KTX של ספריית החיובים ב-Google Play כולל תוספים של Kotlin ותמיכה ב-coroutines, שמאפשרים לכם לכתוב קוד Kotlin אידיומטי כשאתם משתמשים בספריית החיובים ב-Google Play. כדי לכלול את התוספים האלה בפרויקט, מוסיפים את התלות הבאה לקובץ build.gradle של האפליקציה, כמו שמוצג:

    dependencies {
  val billing_version = "9.0.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.getLinkUri()
if (!linkUri.isNullOrEmpty()) {
  val intent = Intent(Intent.ACTION_VIEW, Uri.parse(linkUri))
  context.startActivity(intent)
}

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