מערכת החיוב של 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 הזה כדי לבדוק את סטטוס המינוי ולנהל רכישות של מינויים.
- ספריית החיובים ב-Play גרסה 5 החדשה מאפשרת לאפליקציה ליהנות מכל התכונות החדשות של המינויים. כשתהיו מוכנים לשדרג לגרסה 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 נעשה שימוש רק בישויות החדשות של המינויים. אחרי שתתחילו לערוך את המינויים ב-Console, לא תוכלו יותר להשתמש ב-inappproducts API למינויים.
אם השתמשתם ב-Publishing API לפני מאי 2022, כדי למנוע בעיות, כל המינויים הקיימים מוצגים עכשיו ב-Google Play Console כמינויים לקריאה בלבד. אם תנסו לבצע שינויים, יכול להיות שתופיע אזהרה שמסבירה את המגבלה הזו. לפני שממשיכים לערוך מינויים ב-Console, צריך לעדכן את השילוב של ה-Backend כדי להשתמש בנקודות הקצה החדשות של 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 כוללת את כל השיטות והאובייקטים שזמינים בגרסאות קודמות.
אובייקטים ופונקציות כמו querySkuDetailsAsync() עדיין קיימים, כך שתוכלו לשדרג כדי להשתמש בפונקציונליות חדשה בלי שתצטרכו לעדכן באופן מיידי גם את קוד המינויים הקיים.SkuDetails
אפשר גם לקבוע אילו מבצעים יהיו זמינים באמצעות השיטות האלה על ידי סימון שלהם כבעלי תאימות לאחור.
בנוסף לשיטות הקודמות, ספריית החיובים ב-Play בגרסה 5 כוללת עכשיו אובייקט ProductDetails חדש ושיטה queryProductDetailsAsync() תואמת לטיפול בישויות ובתכונות חדשות. ProductDetails תומך עכשיו גם במוצרים קיימים מתוך האפליקציה (רכישות חד-פעמיות ופריטים מתכלים).
במינוי, הפונקציה ProductDetails.getSubscriptionOfferDetails() מחזירה רשימה של כל תוכניות הבסיס והמבצעים שהמשתמש זכאי לרכוש.
כלומר, אתם יכולים לגשת לכל המינויים הבסיסיים ולכל המבצעים שהמשתמש זכאי להם, בלי קשר לתאימות לאחור.
getSubscriptionOfferDetails() החזרות null של מוצרים שלא נרכשו במסגרת מינוי. לרכישות חד-פעמיות, אפשר להשתמש ב-getOneTimePurchaseOfferDetails().
ספריית החיובים ב-Play בגרסה 5 כוללת גם שיטות חדשות וגם שיטות קודמות להפעלת תהליך הרכישה. אם אובייקט BillingFlowParams שמועבר אל BillingClient.launchBillingFlow() מוגדר באמצעות אובייקט SkuDetails, המערכת מחלצת את פרטי המבצע למכירה מתוך המינוי הבסיסי או המבצע שתואמים למק"ט. אם האובייקט BillingFlowParams שמועבר אל BillingClient.launchBillingFlow() מוגדר באמצעות אובייקטים מסוג ProductDetailsParams, שכוללים את ProductDetails ואת String שמייצג את טוקן המבצע הספציפי של המבצע שנרכש, המערכת משתמשת במידע הזה כדי לזהות את המוצר שהמשתמש רוכש.
queryPurchasesAsync() מחזירה את כל הרכישות שבבעלות המשתמש. כדי לציין את סוג המוצר המבוקש, אפשר להעביר ערך של BillingClient.SkuType, כמו בגרסאות קודמות, או אובייקט QueryPurchasesParams שמכיל ערך של BillingClient.ProductType שמייצג את ישויות המינוי החדשות.
מומלץ לעדכן את האפליקציות לגרסה 5 של הספרייה בהקדם האפשרי, כדי שתוכלו להתחיל ליהנות מהתכונות החדשות האלה של המינויים.
ניהול סטטוס המינוי
בקטע הזה מתוארים השינויים העיקריים ברכיבי ה-Backend של שילוב מערכת החיוב של 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 למינויים בתשלום מראש
נוספו שדות חדשים לתמיכה במינויים בתשלום מראש, שהמשתמש מאריך אותם במקום שהם יתחדשו אוטומטית. כל השדות רלוונטיים למינויים בתשלום מראש בדיוק כמו למינויים שמתחדשים אוטומטית, למעט המקרים הבאים:
- [New field] 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.offerPhase (מזהה את השלב הנוכחי: תקופת ניסיון בחינם, מחיר היכרות, חיוב יחסי, מחיר בסיסי) |
| (אין שדה מקביל) | 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 |
lineItems.autoRenewingPlan.recurringPrice |
introductoryPriceInfo |
lineItems.offerPhase.introductoryPriceהמידע הזה מופיע גם ב offer של כל מינוי שרכשתם. |
| developerPayload | (no equivalent field) developer payload has been deprecated |
| 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. השיטה הזו מקבלת מחיר יחיד בכל מטבע שנתמך ב-Play ומחזירה מחירים מומרים (כולל שיעור מס ברירת המחדל, אם רלוונטי) לכל האזורים שבהם Google Play תומך ברכישות.