מערכת החיוב של Google Play היא שירות שמאפשר לכם למכור מוצרים דיגיטליים ותוכן באפליקציה ל-Android. במהדורה של מאי 2022 שינינו את האופן שבו מוגדרים מוצרים מינויים, והשינוי הזה משפיע על האופן שבו הם נמכרים באפליקציה ומנוהלים בקצה העורפי. אם אתם מבצעים את השילוב עם החיוב ב-Google Play בפעם הראשונה, תוכלו להתחיל את השילוב אחרי שתקראו את המאמר הכנות.
אם מכרתם מינויים באמצעות החיוב ב-Google Play לפני מאי 2022, חשוב להבין איך להשתמש בתכונות החדשות תוך שמירה על המינויים הקיימים.
הדבר הראשון שחשוב לדעת הוא שכל המינויים, האפליקציות והשילובים הקיימים לקצה העורפי פועלים בדיוק כמו שהם פעלו לפני השקת הגרסה במאי 2022. אין צורך לבצע שינויים מיידיים, ותוכלו להתחיל להשתמש בתכונות החדשות האלה לאורך זמן. התמיכה בכל מהדורה ראשית של Google Play Billing Library נמשכת שנתיים ממועד ההשקה. השילובים הקיימים עם Google Play Developer API ימשיכו לפעול כמו קודם.
סקירה כללית של העדכונים במאי 2022:
- בGoogle Play Console החדש אפשר ליצור ולנהל מינויים, תוכניות בסיס ומבצעים. הנתון הזה כולל גם מינויים חדשים וגם מינויים שהועברו.
- Play Developer API מכיל עדכונים שמאפשרים תמיכה בפונקציונליות החדשה של ממשק המשתמש של Google Play Console, באמצעות ממשק API. חשוב לציין שיש גרסה חדשה של Subscription Purchases API. אפשר להשתמש ב-API הזה כדי לבדוק את סטטוס המינוי ולנהל את רכישות המינויים.
- גרסה 5 של ספריית החיובים ב-Play מאפשרת לכם ליהנות מכל התכונות החדשות של מינויים באפליקציה. כשתהיו מוכנים לשדרג לגרסה 5, עליכם לפעול לפי ההנחיות שמפורטות במדריך להעברת נתונים.
הגדרת המינויים
ניהול מינויים דרך Google Play Console
החל ממאי 2022, תבחינו בהבדלים מסוימים ב-Google Play Console.
מעכשיו, לכל מינוי יכולים להיות כמה מינויים בסיסיים ומבצעים. מק"טים של מינויים שנוצרו בעבר מופיעים עכשיו ב-Play Console כאובייקטים חדשים של מינויים, תוכניות בסיס ומבצעים. אם עדיין לא עשיתם זאת, כדאי לעיין במאמר שינויים אחרונים במינוי ב-Play Console כדי לקבל תיאורים של העצמים החדשים, כולל הפונקציונליות וההגדרה שלהם. כל מוצרי המינוי הקיימים שלכם יופיעו בפורמט החדש הזה ב-Google Play Console. כל מק"ט מיוצג עכשיו באובייקט מינוי שמכיל תוכנית בסיס אחת ומבצע תואם לאחור, אם רלוונטי.
שילובים ישנים יותר ציפו שכל מינוי יכלול מבצע אחד, שמיוצג באובייקט SkuDetails. לכן, לכל מינוי יכול להיות מבצע או תוכנית בסיסית אחת עם תאימות לאחור.
המינוי הבסיסי או המבצע שתומכים בתאימות לאחור מוחזרים כחלק ממק"ט באפליקציות שמשתמשות בשיטה querySkuDetailsAsync() שהוצאה משימוש.
למידע נוסף על הגדרה וניהול של מבצעים שתואמים לגרסאות קודמות, ראו הסבר על מינויים. אחרי שהאפליקציה שלכם תשתמש רק ב-queryProductDetailsAsync(), ולא יהיו יותר גרסאות ישנות של האפליקציה שבהן מתבצעות רכישות, לא תצטרכו יותר להשתמש במבצע שתואמת לגרסאות קודמות.
ניהול מינויים באמצעות Subscriptions Publishing API
Play Developer API מכיל פונקציונליות חדשה לרכישת מינויים. ה-API של inappproducts לניהול מק"טים ממשיך לפעול כמו בעבר, כולל טיפול במוצרים לרכישה חד-פעמית ובמינויים, כך שאין צורך לבצע שינויים מיידיים כדי לשמור על השילוב.
עם זאת, חשוב לציין שב-Google Play Console נעשה שימוש רק בישות המינויים החדשות. אחרי שמתחילים לערוך את המינויים במסוף, אי אפשר יותר להשתמש ב-API של inappproducts למינויים.
אם השתמשתם ב-Publishing API לפני מאי 2022, כדי למנוע בעיות, כל המינויים הקיימים מופיעים עכשיו ב-Google Play Console כקריאה בלבד. אם תנסו לבצע שינויים, יכול להיות שתופיע אזהרה עם הסבר על המגבלה הזו. לפני שממשיכים לערוך את המינויים במסוף, צריך לעדכן את השילוב לקצה העורפי כך שישתמש בנקודות הקצה החדשות של Subscription Publishing. נקודות הקצה החדשות monetization.subscriptions, monetization.subscriptions.baseplans ו-monetization.subscriptions.offers מאפשרות לכם לנהל את כל המינויים הבסיסיים והמבצעים הזמינים. בטבלה הבאה אפשר לראות איך השדות השונים ממפים מהישות InAppProduct לאובייקטים החדשים בקטע monetization.subscriptions:
| InAppProduct | מינוי |
|---|---|
packageName |
packageName |
sku |
productId |
status |
basePlans[0].state |
prices |
basePlans[0].regionalConfigs.price |
listings |
כרטיסי מוצר |
defaultPrice |
אין שקילות |
subscriptionPeriod |
basePlans[0].autoRenewingBasePlanType.billingPeriodDuration |
trialPeriod |
basePlans[0].offers[0].phases[0].regionalConfigs[0].free |
gracePeriod |
basePlans[0].autoRenewingBasePlanType.gracePeriodDuration |
subscriptionTaxesAndComplianceSettings |
taxAndComplianceSettings |
עדכון ה-API הנדרש רלוונטי רק ל-Publishing API (ניהול מק"טים).
שינויים בספריית החיוב ב-Play
כדי לתמוך בהעברה הדרגתית, ספריית החיוב ב-Play כוללת את כל השיטות והאובייקטים שזמינים בגרסאות קודמות.
אובייקטים ופונקציות של SkuDetails, כמו querySkuDetailsAsync(), עדיין קיימים, כך שתוכלו לשדרג ולהשתמש בפונקציונליות החדשה בלי שתצטרכו לעדכן באופן מיידי את הקוד הקיים של המינויים.
אתם יכולים גם לקבוע אילו מבצעים יהיו זמינים בשיטות האלה, על ידי סימון שלהם כתואמים לאחור.
בנוסף לשיטות הקודמות, ספריית החיובים ב-Play 5 כוללת עכשיו אובייקט ProductDetails חדש ושיטת queryProductDetailsAsync() תואמת לטיפול בישויות ובפונקציונליות חדשות. עכשיו יש תמיכה ב-ProductDetails גם במוצרים קיימים מתוך האפליקציה (רכישות חד-פעמיות ומוצרים חד-פעמיים).
עבור מינוי, הפונקציה ProductDetails.getSubscriptionOfferDetails() מחזירה רשימה של כל התוכניות הבסיסיות והמבצעים שהמשתמש זכאי לרכוש.
המשמעות היא שתוכלו לגשת לכל המינויים הבסיסיים והמבצעים שעומדים בדרישות של המשתמש, ללא קשר לתאימות לאחור.
הפונקציה getSubscriptionOfferDetails() מחזירה את הערך null למוצרים שלא כוללים מינוי. לרכישות חד-פעמיות, אפשר להשתמש ב-getOneTimePurchaseOfferDetails().
ב-Play Billing Library 5 יש גם שיטות חדשות וגם שיטות מדור קודם להפעלת תהליך הרכישה. אם האובייקט BillingFlowParams שמוענק ל-BillingClient.launchBillingFlow() מוגדר באמצעות אובייקט SkuDetails, המערכת מחלצת את פרטי המבצע למכירה מהמינוי הבסיסי התואם לאחור או מהמבצע התואם למק"ט. אם האובייקט BillingFlowParams שמוענק ל-BillingClient.launchBillingFlow() מוגדר באמצעות אובייקטים מסוג ProductDetailsParams, שכוללים את ProductDetails ואת String שמייצג את אסימון המבצע הספציפי של המבצע שנרכש, המערכת משתמשת במידע הזה כדי לזהות את המוצר שהמשתמש רוכש.
הפונקציה queryPurchasesAsync() מחזירה את כל הרכישות שבבעלות המשתמש. כדי לציין את סוג המוצר המבוקש, אפשר להעביר ערך BillingClient.SkuType, כמו בגרסאות ישנות יותר, או אובייקט QueryPurchasesParams שמכיל ערך BillingClient.ProductType שמייצג את ישויות המינוי החדשות.
מומלץ לעדכן את האפליקציות לגרסה 5 של הספרייה בקרוב כדי שתוכלו להתחיל ליהנות מהתכונות החדשות האלה של המינוי.
ניהול סטטוס המינוי
בקטע הזה מתוארים השינויים העיקריים ברכיבי הקצה העורפי של השילוב של מערכת החיוב של Google Play, שצריך להטמיע כדי לעבור לגרסה 5.
התראות בזמן אמת למפתחים
בקרוב האובייקט SubscriptionNotification לא יכיל יותר את המאפיין subscriptionId. אם אתם מסתמכים על השדה הזה כדי לזהות את מוצר המינוי, עליכם לעדכן את הקוד כך שיקבל את המידע הזה מסטטוס המינוי באמצעות purchases.subscriptionv2:get אחרי שתקבלו את ההתראה. כל רכיב SubscriptionPurchaseLineItem בקולקציה lineItems שמוחזר כחלק מסטטוס הרכישה יכלול את productId התואם.
Subscriptions Purchases API: אחזור סטטוס המינוי
בגרסאות קודמות של Subscriptions Purchases API, אפשר היה לשלוח שאילתה לגבי סטטוס המינוי באמצעות purchases.subscriptions:get.
נקודת הקצה הזו לא השתנתה וממשיכה לפעול לרכישות של מינויים עם תאימות לאחור. נקודת הקצה הזו לא תומכת בפונקציות חדשות שהושקו במאי 2022.
בגרסה החדשה של Subscriptions Purchases API, משתמשים ב-purchases.subscriptionsv2:get כדי לקבל את סטטוס רכישת המינוי. ה-API הזה תואם למינויים שהועברו, למינויים חדשים (בתשלום מראש וגם עם חידוש אוטומטי) ולרכישות מכל הסוגים. אפשר להשתמש בנקודת הקצה הזו כדי לבדוק את סטטוס המינוי כשמקבלים התראות. האובייקט המוחזר, SubscriptionPurchaseV2, מכיל שדות חדשים, אבל הוא עדיין כולל נתונים מדור קודם שנדרשים כדי להמשיך לתמוך במינוי הקיים.
שדות SubscriptionPurchaseV2 לתוכניות בתשלום מראש
נוספו שדות חדשים לתמיכה במינויים בתשלום מראש, שהמשתמשים יכולים להרחיב במקום שהם יתחדשו באופן אוטומטי. כל השדות רלוונטיים למינויים בתשלום מראש כמו למינויים שמתחדשים אוטומטית, מלבד החריגים הבאים:
- [שדה חדש] lineItems[0].prepaid_plan.allowExtendAfterTime: השדה הזה מציין מתי משתמש יוכל לקנות תוספת זמן נוספת כדי להאריך את התוכנית בתשלום מראש, כי לכל משתמש מותר להחזיק רק תוספת זמן אחת שלא נוצלה בכל פעם.
- [שדה חדש] SubscriptionState: מציין את המצב של אובייקט המינוי.
בתוכניות בתשלום מראש, הערך הזה הוא תמיד
ACTIVE,PENDINGאוCANCELED. - lineItems[0].expiryTime: השדה הזה תמיד מופיע בתוכניות בתשלום מראש.
- paused_state_context: השדה הזה אף פעם לא מופיע, כי אי אפשר להשהות תוכניות בתשלום מראש.
- lineItems[0].auto_renewing_plan: לא מופיע במינויים בתשלום מראש.
- canceled_state_context: השדה הזה לא מופיע בתוכניות בתשלום מראש, כי הוא רלוונטי רק למשתמשים שמבטלים מינוי באופן פעיל.
- lineItems[0].productId: השדה הזה מחליף את
subscriptionIdמגרסאות קודמות.
שדות SubscriptionPurchaseV2 למינויים קבועים
purchases.subscriptionv2 מכיל שדות חדשים שמספקים פרטים נוספים על אובייקטים חדשים של מינויים. בטבלה הבאה מוסבר איך השדות מנקודת הקצה של המינוי מהדור הקודם ממפים לשדות התואמים ב-purchases.subscriptionv2.
| SubscriptionPurchase | SubscriptionPurchaseV2 |
|---|---|
countryCode |
regionCode |
orderId |
latestOrderId |
| (אין שדה מקביל) | lineItems (רשימת SubscriptionPurchaseLineItem) שמייצגת את המוצרים שנרכשו ברכישה |
| (אין שדה מקביל) | lineItems.offerDetails.basePlanId |
| (אין שדה מקביל) | lineItems.offerDetails.offerId |
| (אין שדה מקביל) | lineItems.offerDetails.offerTags |
startTimeMillis |
startTime |
expiryTimeMillis |
lineItems.expiryTime (לכל מינוי שנרכש ברכישה יש expiryTime משלו) |
| (אין שדה מקביל) | subscriptionState (מציין את
הסטטוס של המינוי) |
| (אין שדה מקביל) | pausedStateContext (מופיע רק אם סטטוס המינוי הוא SUBSCRIPTION_STATE_PAUSED) |
autoResumeTimeMillis |
pausedStateContext.autoResumeTime |
| (אין שדה מקביל) | canceledStateContext (מופיע רק אם סטטוס המינוי הוא SUBSCRIPTION_STATE_CANCELED) |
| (אין שדה מקביל) | testPurchase (מופיע רק ברכישות של בודקים מורשים) |
autoRenewing |
lineItems.autoRenewingPlan.autoRenewEnabled |
priceCurrenceCode,
priceAmountMicros,
introductoryPriceInfo |
(אין שדה מקביל) המידע הזה מופיע ב- basePlan/offer לכל אחד מהמינויים שנרכשו. |
| developerPayload | (אין שדה מקביל) עומס העבודה של המפתח הוצא משימוש |
| paymentState | (אין שדה מקביל) אפשר להסיק את סטטוס התשלום מהשדה subscriptionState:
|
cancelReason,
userCancellationTimeMillis,
cancelSurveyResult |
canceledStateContext |
linkedPurchaseToken |
linkedPurchaseToken (ללא שינוי) |
purchaseType |
בדיקה: דרך testPurchaseמבצע: signupPromotion |
priceChange |
lineItems.autoRenewingPlan.priceChangeDetails |
profileName,
emailAddress,
givenName,
familyName,
profileId |
subscribeWithGoogleInfo |
acknowledgementState |
acknowledgementState (no change) |
promotionType,
promotionCode |
signupPromotion |
externalAccountId,
obfuscatedExternalAccountId,
obfuscatedExteranlProfileId |
externalAccountIdentifiers |
פונקציות אחרות לניהול מינויים
אמנם purchases.subscriptions:get שודרג ל-purchases.subscriptionsv2:get, אבל שאר הפונקציות לניהול מינויים של מפתחים לא השתנו בינתיים בנקודת הקצה purchases.subscriptions, כך שתוכלו להמשיך להשתמש ב-purchases.subscriptions:acknowledge, ב-purchases.subscriptions:cancel, ב-purchases.subscriptions:defer, ב-purchases.subscriptions:refund וב-purchases.subscriptions:revoke כמו בעבר.
Pricing API
משתמשים בנקודת הקצה monetization.convertRegionPrices כדי לחשב מחירים אזוריים, כמו שאפשר לעשות דרך Play Console. ה-method הזה מקבל מחיר יחיד בכל מטבע שנתמך ב-Play ומחזיר מחירים המומרים (כולל שיעור ברירת המחדל של המס, במקרים הרלוונטיים) לכל האזורים שבהם יש תמיכה ברכישות ב-Google Play.