רכישות של מינויים יכולות לעבור כמה מצבים שונים במהלך מחזור החיים שלהן, בהתאם להרבה גורמים, כולל התנהגות החידוש האוטומטי, מצבים של דחיית תשלום ופעולות ניהול של המפתחים.
ניהול מחזור החיים של מינויים שמתחדשים אוטומטית
כשמצב המינוי של משתמש משתנה, שרת הקצה העורפי מקבל הודעה מסוג SubscriptionNotification.
כדי לעדכן את הסטטוס בקצה העורפי, קוראים ל-API purchases.subscriptionsv2.get עם אסימון הרכישה שכלול בהתראה. נקודת הקצה הזו מספקת את המצב העדכני של המינוי בהינתן טוקן רכישה, והיא נחשבת למקור האמת לניהול מינויים.
אסימון הרכישה תקף ממועד ההרשמה למינוי ועד 60 יום אחרי תאריך התפוגה. אחרי התאריך הזה, אי אפשר יותר להשתמש באסימון הרכישה כדי לבצע קריאה לממשק API של Google Play למפתחים.
רכישות חדשות של מינויים שמתחדשים אוטומטית
כשמשתמש רוכש מינוי, הודעה מסוג SubscriptionNotification עם הערך SUBSCRIPTION_PURCHASED נשלחת ללקוח ה-RTDN שלכם. בין אם קיבלתם את ההתראה הזו או רשמתם רכישה חדשה מתוך האפליקציה באמצעות PurchasesUpdatedListener או אחזור ידני של רכישות בשיטה onResume() של האפליקציה, עליכם לעבד את הרכישה החדשה בקצה העורפי המאובטח שלכם. לשם כך, בצע את הצעדים הבאים:
- שולחים שאילתה לנקודת הקצה
purchases.subscriptionsv2.getכדי לקבל משאב מינוי שמכיל את הסטטוס העדכני של המינוי. - מוודאים שהערך של השדה
subscriptionStateהואSUBSCRIPTION_STATE_ACTIVE. - מאמתים את הרכישה.
- נותנים למשתמש גישה לתוכן. אפשר לזהות את חשבון המשתמש שמשויך לרכישה באמצעות האובייקט
ExternalAccountIdentifiersממקור המידע של המינוי, אם המזהים הוגדרו בזמן הרכישה באמצעותsetObfuscatedAccountIdו-setObfuscatedProfileId.
השדה offerPhase ב-SubscriptionPurchaseLineItem מספק פרטים על השלב הנוכחי של המינוי, כמו תקופת ניסיון בחינם או מחיר היכרות.
ספריית החיוב של Play כוללת גם שיטה לאישור מינוי, acknowledgePurchase(), ושיטה לבדיקת סטטוס האישור, isAcknowledged().
עם זאת, מומלץ לטפל בעיבוד הרכישות בקצה העורפי שלכם כדי לשפר את האבטחה.
משאב המינוי לרכישות חדשות נראה בערך כך:
{
"kind": "androidpublisher#subscriptionPurchaseV2",
"startTime": "2022-04-22T18:39:58.270Z",
"regionCode": "US",
"subscriptionState": "SUBSCRIPTION_STATE_ACTIVE",
"latestOrderId": "GPA.3333-4137-0319-36762",
"acknowledgementState": "ACKNOWLEDGEMENT_STATE_PENDING", // need to acknowledge new purchases
"lineItems": [
{
"productId": "sub_variant_plan01",
"expiryTime": next_renewal_date,
"autoRenewingPlan": {
"autoRenewEnabled": true
},
"offerPhase": {
"freeTrial": {}
}
}
],
}
חידושים של מינויים
במינויים שמתחדשים אוטומטית ולא כוללים תשלומים, תישלח הודעה כשהמינוי יתחדש.SUBSCRIPTION_RENEWED במינויים בתשלומים, נשלחת התראה SUBSCRIPTION_RENEWED בכל פעם שהמינוי מחויב בתאריך החיוב שלו. צריך לוודא שהמשתמש עדיין זכאי למינוי, ואז לעדכן את סטטוס המינוי באמצעות הערך החדש של expiryTime שמופיע במשאב המינוי שמוחזר מ-Google Play Developer API. משאב המינוי אמור להיראות כך:
{
"kind": "androidpublisher#subscriptionPurchaseV2",
"startTime": "2022-04-22T18:39:58.270Z",
"regionCode": "US",
"subscriptionState": "SUBSCRIPTION_STATE_ACTIVE",
"latestOrderId": "GPA.3333-4137-0319-36762",
"acknowledgementState": "ACKNOWLEDGEMENT_STATE_ACKNOWLEDGED",
"lineItems": [
{
"productId": "sub_variant_plan01",
"expiryTime": next_renewal_date,
"autoRenewingPlan": {
"autoRenewEnabled": true
},
"offerPhase": {
"basePrice": {}
}
}
]
}
אין צורך לאשר חידוש מינוי.
תקופת חסד
אם יש בעיות בתשלום על חידוש המינוי, Google מודיעה למשתמש ומנסה לחדש את המינוי מעת לעת במשך תקופה מסוימת לפני שהמינוי יפוג. תקופת השחזור יכולה לכלול תקופת חסד ואחריה תקופת השהיית החשבון. במהלך תקופת החסד, למשתמש עדיין צריכה להיות גישה לזכאות שלו למינוי.
השיטה
queryPurchasesAsync()
ממשיכה להחזיר רכישות שנמצאות בתקופת החסד. אם האפליקציה שלך מסתמכת רק על queryPurchasesAsync כדי לבדוק אם למשתמש יש זכאות למינוי, האפליקציה צריכה לטפל אוטומטית בתקופות החסד, כי המינויים האלה מוצגים כפעילים דרך ספריית החיובים ב-Play.
סנכרון סטטוס המינוי עם ה-Backend מאפשר לכם לקבל מידע על דחיות תשלום, ונותן לכם יותר הקשר כשאתם מנסים להפחית את הנטישה הלא רצונית. האזנה להודעות מסוג SUBSCRIPTION_IN_GRACE_PERIOD של SubscriptionNotification כדי לקבל התראה כשהמשתמש נכנס לתקופת חסד. בזמן שהמשתמש נמצא בתקופת חסד, subscription
resource
מכיל autoRenewEnabled = true. מערכת Google Play מאריכה באופן דינמי את הערך של expiryTime עד שתקופת החסד מסתיימת, כי הזכאות צריכה להימשך עד שהמשתמש מבטל את המינוי או עד שתקופת החסד מגיעה לאורך המקסימלי שלה. הערך של השדה subscriptionState בתקופה הזו הוא SUBSCRIPTION_STATE_IN_GRACE_PERIOD. משאב המינוי אמור להיראות כך:
{
"kind": "androidpublisher#subscriptionPurchaseV2",
...
"subscriptionState": "SUBSCRIPTION_STATE_IN_GRACE_PERIOD",
...
"lineItems": [
{
"productId": "sub_variant_plan01",
"expiryTime": timestamp_in_future,
"autoRenewingPlan": {
"autoRenewEnabled": true
}
}
],
}
משתמשים שנמצאים בתקופת חסד מקבלים הודעה מ-Play על כך שהתשלום שלהם נדחה, ומוצגת להם הנחיה לפתור את הבעיות באמצעי התשלום בחנות Play. כשמשתמש נכנס לתקופת חסד, כדאי לעודד אותו לתקן את אמצעי התשלום שלו, למקרה שהכישלון לא היה מכוון. דרך פשוטה לעשות את זה היא באמצעות In-App Messaging API. אם קוראים ל-API הזה כשהמשתמש פותח את האפליקציה, מוצגת לו הודעה זמנית ב-Play, שמיידעת אותו שהתשלום שלו נדחה. ההודעה הזו כוללת גם קישור עומק שמאפשר למשתמש לתקן את אמצעי התשלום שלו ב-Google Play.
ברגע שהמשתמש יתקן את אמצעי התשלום, המינוי יתחדש בתאריך החידוש המקורי, ותוכלו לטפל בחידוש כמו שמתואר בקטע חידושים.
אם המשתמש לא יתקן את אמצעי התשלום במהלך תקופת החסד, המינוי יעבור להמתנה להסדרת החוב והמשתמש יאבד את הזכאות למינוי.
גישה לחשבון ושחזור שלו בתקופת החסד
איור 2 מציג ציר זמן של מינוי שנכנס לתקופת חסד ואז משתקם כשהמשתמש מתקן את אמצעי התשלום שלו. בתום תקופת החסד, המשתמש יאבד את ההטבות של המינוי והחשבון שלו יועבר להשהיה.
חשוב לזכור את הנקודות הבאות:
- במהלך תקופת החסד, המשתמש צריך לשמור על הגישה להטבות המינוי.
- כשמינוי חוזר לפעולה במהלך תקופת החסד, תאריך החידוש לא מתאפס.
- אם תשנו את תקופת החסד, השינוי לא ישפיע על משתמשים שנמצאים כרגע בתקופת חסד. אם המינוי יגיע לחידוש אחרי השינוי, תקופת החסד החדשה תתעדכן. לדוגמה, אם משנים את תקופת החסד מ-7 ימים ל-14 ימים, משתמשים שנכנסים לתקופת החסד אחרי השינוי יקבלו את תקופת החסד החדשה של 14 ימים.
- המינוי נשאר פעיל ולא תקבלו הודעה על תקופת חסד עד שתקופת החסד השקטה תסתיים
תקופת חסד שקטה
אפשר להגדיר תקופת חסד של 0 ימים, אבל מערכת Play תמתין לפחות יום אחד כדי לוודא שיש מספיק זמן לניסיונות חוזרים של תשלום. תקופת החסד השקטה הזו מספקת רשת ביטחון לעיבוד התשלומים. במהלך 24 השעות האלה, המינוי נשאר בסטטוס ACTIVE.
הדרך הכי טובה להתעדכן בשינויים בסטטוס המינוי היא להאזין להתראות בזמן אמת למפתחים (RTDN) ולפעול בהתאם. כדי לקבל סטטוס מדויק יותר של המינוי, צריך להתקשר לשיטת purchases.subscriptionsv2.get() בזמן ה-RTDN במקום במועד התפוגה.
בהתאם לסטטוס המינוי אחרי תקופת החסד השקטה של 24 שעות, תקבלו אחת מההתראות הבאות:
-
SUBSCRIPTION_ON_HOLD(אם התכונה הופעלה) SUBSCRIPTION_CANCELED(אם בוטלה)-
SUBSCRIPTION_EXPIRED(אם פג התוקף) -
SUBSCRIPTION_RENEWED(אם החידוש יתבצע בהצלחה)
אפשר גם להתקשר לשיטת subscriptionV2.get() בכל שלב אחרי תקופת החסד השקטה של 24 שעות כדי לקבל את הסטטוס העדכני של המינוי.
השהיית חשבון
אם מציינים אורך שהוא קצר יותר מערך ברירת המחדל, יכול להיות שמספר המינויים שיוחזרו בעקבות סירוב תשלום יהיה קטן יותר.אם יש בעיות בתשלום על חידוש מינוי, אחרי שתקופת החסד מסתיימת, מתחילה תקופת השהיה של החשבון. כשמינוי מושהה, צריך לחסום את הגישה להרשאה של המינוי.
במהלך ההשהיה של החשבון, צריך להמשיך לטפל בביטולים, בשחזורים או ברכישות חוזרות של המינויים לפי הצורך, כי יכול להיות שהמשתמש יבצע את השינויים האלה בזמן שהמינוי מושהה.
התראות בזמן אמת על ניתוקים מודיעות לכם כשהמשתמש נכנס לתקופת השהיית החשבון, כדי שתוכלו להודיע לו בהקדם האפשרי למה הגישה שלו למינוי הושעתה. דרך פשוטה לעשות את זה היא באמצעות In-App Messaging API. אם תפעילו את ה-API הזה כשהמשתמש יפתח את האפליקציה, תוצג לו הודעה בסרגל אינטראקטיבי זמני שתעדכן אותו שהתשלום שלו נדחה. ההודעה כוללת גם קישור עומק שמאפשר למשתמש לתקן את אמצעי התשלום שלו ב-Google Play.
אם המשתמשים יכולים לגשת לתוכן של המינוי מחוץ לאפליקציה, הם עשויים לגלות שהם איבדו את הגישה בפלטפורמות שונות. מומלץ לשלוח למשתמש התראה בדחיפה או אימייל כדי לעדכן אותו שהמינוי שלו כבר לא פעיל בגלל דחיית התשלום.
המינוי לא מוחזר על ידי השיטה
queryPurchasesAsync()
במהלך השהיית החשבון, ולכן אם האפליקציה שלכם מסתמכת על השיטה הזו כדי להציג רכישות קיימות, כדאי לתמוך בהשהיית החשבון כברירת מחדל.
באמצעות התראות בזמן אמת למפתחים, תקבלו הודעה מסוג SUBSCRIPTION_ON_HOLD עם הערך SubscriptionNotification כשמינוי עובר להמתנה. מתקשרים אל שיטת purchases.subscriptionsv2.get משרת הקצה העורפי המאובטח כדי לאחזר את פרטי המינוי החדשים. במהלך השהיית החשבון, השדה expiryTime של משאב המינוי מוגדר לחותמת זמן מהעבר, והשדה subscriptionState מוגדר ל-SUBSCRIPTION_STATE_ON_HOLD:
{
"kind": "androidpublisher#subscriptionPurchaseV2",
...
"subscriptionState": "SUBSCRIPTION_STATE_ON_HOLD",
...
"lineItems": [
{
"productId": "sub_variant_plan01",
"expiryTime": timestamp_in_past,
...
}
],
}
כדי לשחזר את הגישה, המשתמשים צריכים לתקן את אמצעי התשלום. מערכת Play מודיעה למשתמשים שהחשבון שלהם בהמתנה על תשלום שנדחה, וכדאי גם לכם לעודד אותם לתקן את אמצעי התשלום.
אחרי שהמשתמש יתקן את אמצעי התשלום, המינוי יחזור למצב פעיל ותצטרכו לשחזר את הגישה לתוכן שאליו נרשם המשתמש. במקרה הזה, טוקן הרכישה זהה לטוקן שהיה לפני שהחשבון הושעה, כי מדובר באותה רכישה שמתבצעת מחדש, ואתם מקבלים RTDN עם סוג SUBSCRIPTION_RECOVERED.
במינויים לתשלומים, יכול להיות שיהיו ניסיונות נדחים לחיוב וניסיונות חוזרים לחיוב בכל ניסיון תשלום.
אחרי השחזור, ספריית החיובים ב-Play מחזירה את המינוי שוב דרך השיטה queryPurchasesAsync(). אם אתם משתמשים בשיטה הזו כדי לקבוע אם למשתמש יש זכאות למינוי, האפליקציה שלכם צריכה לטפל באופן אוטומטי בשחזור המינוי ממצב של השהיית החשבון.
צריך להאזין להודעה SubscriptionNotification עם הסוג SUBSCRIPTION_RECOVERED כדי לקבל התראה כשמינוי משוחזר והמשתמש אמור לקבל גישה מחדש. אם תשלחו שאילתה לגבי מינוי אחרי שתקבלו את ההתראה הזו, השדה expiryTime יוגדר לחותמת זמן בעתיד והשדה subscriptionState יוגדר שוב ל-SUBSCRIPTION_STATE_ACTIVE:
{
"kind": "androidpublisher#subscriptionPurchaseV2",
...
"subscriptionState": "SUBSCRIPTION_STATE_ACTIVE",
...
"lineItems": [
{
"productId": "sub_variant_plan01",
"expiryTime": next_renewal_date,
...
}
],
}
אם המשתמש לא יתקן את אמצעי התשלום לפני סיום תקופת ההמתנה של החשבון, תקבלו במקום זאת הודעת RTDN מסוג SUBSCRIPTION_CANCELED. הוראות לטיפול בביטול מופיעות במאמר בנושא ביטולים. כשמבצעים שאילתה לגבי מינוי שבוטל בדרך הזו, השדה expiryTime שמוחזר מוגדר לחותמת זמן מהעבר:
{
"kind": "androidpublisher#subscriptionPurchaseV2",
...
"subscriptionState": "SUBSCRIPTION_STATE_CANCELED",
...
"lineItems": [
{
"productId": "sub_variant_plan01",
"expiryTime": timestamp_in_past,
...
}
],
}
מיד אחרי שתקבלו הודעה על הביטול במהלך השהיית החשבון, תקבלו גם RTDN עם סוג SUBSCRIPTION_EXPIRED כי המשתמש לא זכאי יותר למינוי בתשלום והמינוי בוטל.
אתם יכולים לטפל בתפוגה הזו כרגיל.
המשתמש יכול לקבל שוב גישה למינוי על ידי רכישה מחדש של אותו מינוי או של מינוי אחר שאתם מציעים דרך האפליקציה במהלך תקופת ההשעיה של החשבון, החל מהרכישה המקורית. במקרה כזה, מונפק טוקן רכישה חדש והערך החדש מוחזר כחלק מאירוע SUBSCRIPTION_PURCHASED שמייצג את המופע החדש הזה.
גישה לחשבון בהשהיה ושחזור החשבון
איור 3 מציג ציר זמן של מינוי שהחשבון שלו מושהה ואז חוזר לפעולה אחרי שהמשתמש מתקן את אמצעי התשלום.
בדומה לדוגמה הקודמת, באיור 4 מוצג ציר זמן של מינוי שנכנס לתקופת חסד לפני שהוא מושהה, ואז חוזר לפעילות בזמן ההשהיה.
חשוב לזכור את הנקודות הבאות:
- לפני שהמינוי עובר להקפאת החשבון, מערכת Google Play מנסה שוב לחייב את אמצעי התשלום במשך עד 48 שעות. במהלך התקופה הזו, המשתמש שומר על ההטבות של המינוי. אחרי שתקופת הניסיון החוזר תסתיים, המינוי יעבור להשהיית החשבון והמשתמש יאבד את הגישה להטבות המינוי.
- המינוי עובר להשהיית חשבון ישירות כשמחדשים אותו ממצב השהיה ואמצעי התשלום לא תקין.
- כשמינוי חוזר לפעילות אחרי שהחשבון הושהה, תאריך החידוש מתאפס.
זמני תפוגה
אחרי שמינוי מסתיים, הגישה של המשתמש למינוי אמורה להתבטל. הודעה מסוג SUBSCRIPTION_EXPIRED נשלחת במקרה כזה.SubscriptionNotification כשמקבלים את ההתראה הזו, צריך לשלוח שאילתה אל Google Play Developer API כדי לקבל את משאב המינוי העדכני.
אחרי שמאשרים שהערך של subscriptionState הוא SUBSCRIPTION_STATE_EXPIRED,
מסירים את ההרשאה ורושמים את מצב הרכישה כלא תקף בשרת העורפי. משאב המינוי אמור להיראות כך:
{
"kind": "androidpublisher#subscriptionPurchaseV2",
...
"subscriptionState": "SUBSCRIPTION_STATE_EXPIRED",
...
"lineItems": [
{
"productId": "sub_variant_plan01",
"expiryTime": expiration_time_in_past,
...
}
],
}
ביטולים
משתמש יכול לבטל מינוי מרצון במרכז המינויים של Play, או שהמינוי יבוטל אוטומטית אם המשתמש לא ישחזר את החשבון אחרי שהוא יהיה בהמתנה להסדרת החשבון. מפתחים יכולים גם להפעיל ביטול באמצעות purchases.subscriptionsv2.cancel. כשמינוי מבוטל, המשתמש שומר על הגישה לתוכן עד לסיום מחזור החיוב הנוכחי. הגישה אמורה להתבטל בסיום מחזור החיובים.
ביטול מינוי שאינו בתשלומים ומתחדש אוטומטית מפעיל התראה SUBSCRIPTION_CANCELED. כשמקבלים את ההתראה הזו, השדה subscriptionState של משאב המינוי שמוחזר מ-ממשק API של Google Play למפתחים מוגדר לערך SUBSCRIPTION_STATE_CANCELED, והשדה expiryTime מכיל את התאריך שבו המשתמש יאבד את הגישה למינוי. אם התאריך הזה חלף, המשתמש יאבד את ההרשאה באופן מיידי. זה יכול לקרות, לדוגמה, אם משתמש מבטל מינוי בזמן שהחשבון שלו בהמתנה בגלל סירוב תשלום.
משאב המינוי של רכישה שבוטלה נראה בערך כך:
{
"kind": "androidpublisher#subscriptionPurchaseV2",
...
"subscriptionState": "SUBSCRIPTION_STATE_CANCELED",
...
"lineItems": [
{
"productId": "sub_variant_plan01",
"expiryTime": expiration_time,
...
}
],
}
במינויים לתשלומים, תישלח התראה על ביטול שהמשתמש יזום אם נותרו תשלומים לתקופת ההתחייבות.SUBSCRIPTION_CANCELLATION_SCHEDULED הביטול בהמתנה והוא ייכנס לתוקף בסוף תקופת ההתחייבות הנוכחית. כשמקבלים את ההתראה הזו, שדה subscriptionState במשאב המינוי שמוחזר מ-ממשק API של Google Play למפתחים מוגדר לערך SUBSCRIPTION_STATE_ACTIVE כי המינוי לתשלומים עדיין פעיל עד לסיום תקופת ההתחייבות.
עם זאת, קיים אובייקט ריק של pendingCancellation.
תישלח התראה SUBSCRIPTION_CANCELED ואחריה SUBSCRIPTION_CANCELED בסוף תקופת ההתחייבות.SUBSCRIPTION_EXPIRED
משאב המינוי לרכישת מינוי בתשלומים שממתין לביטול אמור להיראות כמו בדוגמה הבאה:
{
"kind": "androidpublisher#subscriptionPurchaseV2",
...
"subscriptionState": "SUBSCRIPTION_STATE_ACTIVE",
...
"lineItems": [
{
"productId": "sub_plan01",
"expiryTime": expiration_time,
"autoRenewingPlan": {
"autoRenewEnabled": true,
"recurringPrice": {
"currencyCode": "USD",
"units": "1",
"nanos": 990000000
},
"installmentDetails": {
"initialCommittedPaymentsCount": 6,
"remainingCommittedPaymentsCount": 5,
"pendingCancellation": {}
...
}
}
}
],
}
אפשר לעיין בשדה canceledStateContext במשאב המינוי כדי להבין למה המינוי בוטל (לדוגמה, אם המינוי בוטל על ידי המשתמש, על ידי המערכת או על ידכם). אם המינוי בוטל על ידי המשתמש, אפשר לבדוק את השדה userInitiatedCancellation כדי להבין למה המשתמש ביטל את המינוי. המידע הזה יכול לעזור לכם לגבש אסטרטגיות תקשורת.
כשמינוי מבוטל אבל עדיין לא פג תוקפו, הוא עדיין מוחזר מ-queryPurchasesAsync().
כדאי להציג באפליקציה הודעה למשתמשים על ביטול המינוי, ולציין את תאריך התפוגה.
ביטולים
יכולות להיות סיבות שונות לביטול מינוי, כולל ביטול המינוי על ידי ה-Backend באמצעות purchases.subscriptionsv2.revoke או ביצוע החזר כספי על הרכישה. במצב כזה, צריך לבטל את ההרשאה של המשתמש באופן מיידי. במקרה כזה, נשלחת הודעת SubscriptionNotification עם סוג SUBSCRIPTION_REVOKED. כשמקבלים את ההתראה הזו, הערך של השדה subscriptionState במשאב המינוי שמוחזר מ-ממשק API של Google Play למפתחים הוא SUBSCRIPTION_STATE_EXPIRED.
משאב המינוי לרכישה שבוטלה נראה דומה לדוגמה הבאה:
{
"kind": "androidpublisher#subscriptionPurchaseV2",
...
"subscriptionState": "SUBSCRIPTION_STATE_EXPIRED",
...
"lineItems": [
{
"productId": "sub_variant_plan01",
"expiryTime": expiration_time,
...
}
]
}
מינויים שנדחו
יכולות להיות מגוון סיבות שבגללן כדאי להאריך את ההרשאה של משתמש. לדוגמה, יכול להיות שתרצו להציע למשתמשים גישה חינמית כקידום מכירות מיוחד, כמו שבוע חינם ברכישת סרט או גישה חינמית ללקוחות כמחווה של רצון טוב.
אפשר להשתמש ב-purchases.subscriptionsv2.defer API כדי לדחות את תאריך החיוב של מינויים (כולל מינויים עם חבילות). כשדוחים את תאריך החיוב של מינוי עם חבילות, תאריך החיוב של כל הפריטים במינוי נדחה למשך הזמן שצוין.
כשדוחים את החיוב על מינוי, נשלחת הודעה מסוג SUBSCRIPTION_DEFERRED עם SubscriptionNotification. במהלך תקופת הדחייה, המשתמש נרשם לתוכן שלכם עם גישה מלאה, אבל לא מחויב. תאריך חידוש המינוי מתעדכן בהתאם לתאריך החדש.
בתוכניות בתשלום מראש, אפשר להשתמש ב-API לדחיית החיוב כדי לדחות את מועד התפוגה.
משאב המינוי למינוי שנדחה נראה כך:
{
"kind": "androidpublisher#subscriptionPurchaseV2",
...
"subscriptionState": "SUBSCRIPTION_STATE_ACTIVE",
...
"lineItems": [
{
"productId": "sub_variant_plan01",
"expiryTime": timestamp_in_future,
...
}
],
}
מינויים שהושהו
כדי להפחית נטישה מכוונת, אפשר לאפשר למשתמשים להשהות את המינוי. כשמפעילים את תכונת ההשהיה, המשתמשים יכולים להשהות את המינוי לתקופה של שבוע עד שלושה חודשים, בהתאם לתקופה החוזרת. הפעולה הזו תשעה את המינוי באופן זמני.
| מחזור חיוב של מינוי | שבועי | חודשי | לשלושה חודשים | לשישה חודשים | שנתי |
|---|---|---|---|---|---|
| משך ההפסקה האפשרי* | שבוע אחד שבועיים 3 שבועות 4 שבועות |
חודש אחד חודשיים 3 חודשים |
חודש אחד חודשיים 3 חודשים |
חודש אחד חודשיים 3 חודשים |
לא רלוונטי |
ההשהיה של המינוי מתחילה רק אחרי שתקופת החיוב הנוכחית מסתיימת. בזמן שהמינוי מושהה, למשתמש אין גישה למינוי והוא לא משלם את מחיר החידוש. בסיום תקופת ההשהיה, המינוי יופעל מחדש ו-Google תנסה לחדש אותו. אם החידוש יתבצע בלי בעיות, המינוי יחזור להיות פעיל. אם החידוש נכשל בגלל בעיה בתשלום, המשתמש עובר למצב של השהיית החשבון, כמו שמוצג באיורים 5 ו-6:
משתמש יכול גם לבחור להפעיל מחדש מינוי באופן ידני בכל שלב במהלך תקופת ההשהיה, כפי שמוצג באיור 6. כשמשתמש מחדש את המינוי באופן ידני, תאריך החיוב משתנה לתאריך החידוש הידני.
כשמינוי של משתמש מושהה, ספריית החיובים ב-Play לא מחזירה את המינוי באמצעות השיטה queryPurchasesAsync(), אלא אם הפרמטר includeSuspendedSubscriptions מוגדר כ-true ב-QueryPurchasesParams. אם המינוי מופעל מחדש, השיטה queryPurchasesAsync() מחזירה אותו שוב.
כדאי להאזין להתראות בזמן אמת כדי לדעת מתי משתמש משהה את המינוי שלו. ההתראות האלה מאפשרות לכם גם להודיע למשתמשים באפליקציה שהם השהו את המינוי ואין להם גישה אליו. אתם צריכים גם לספק למשתמש דרך להפעיל מחדש את המינוי שלו באופן ידני בכל שלב באמצעות קישור עומק ל-Google Play.
הודעת SubscriptionNotification עם הסוג SUBSCRIPTION_PAUSE_SCHEDULE_CHANGED נשלחת כשהמשתמש מתחיל להשהות את המינוי. בשלב הזה, הגישה של המשתמש למינוי צריכה להימשך עד לתאריך החידוש הבא, ובמקור המידע של המינוי צריך להיות הערך autoRenewEnabled = true. הערך בשדה subscriptionState הוא SUBSCRIPTION_STATE_ACTIVE בשלב הזה.
הודעה מסוג SUBSCRIPTION_PAUSED עם הערך SubscriptionNotification נשלחת כשההשהיה נכנסת לתוקף. במקרה כזה, המשתמש אמור לאבד את הגישה למינוי שלו, ובמשאב המינוי יופיע autoRenewEnabled = true, והשדה subscriptionState יוגדר לערך SUBSCRIPTION_STATE_PAUSED. אפשר לבדוק את אובייקט PausedStateContext כדי לראות מתי המינוי צפוי להתחדש שוב.
הודעה מסוג SubscriptionNotification עם הערך SUBSCRIPTION_RECOVERED נשלחת אם
המינוי מתחדש אוטומטית בסיום תקופת ההשהיה
או אם המשתמש בחר לחדש את המינוי באופן ידני.
הודעה מסוג SubscriptionNotification עם סוג SUBSCRIPTION_ON_HOLD נשלחת אם
הייתה בעיה בתשלום במהלך הניסיון לחדש את המינוי אחרי השהיה.
בשני המקרים, צריך לפעול כמו שמתואר בקטע השעיית חשבון.
הרשמה מחדש
במינויים בסיסיים שמתחדשים אוטומטית, יכול להיות שיוצג בחנות Google Play לחצן הרשמה מחדש. הכפתור הזה מאפשר למשתמשים לקבל שוב גישה למינוי. יכולות להיות סיבות שונות לכך שהיא לא מופיעה, למשל אם תוקף המינוי פג לפני זמן רב.
הכיתוב על הלחצן הוא תמיד חידוש המינוי, אבל הפונקציונליות שלו משתנה בהתאם למצב המינוי.
אם מינוי בוטל אבל עדיין לא פג, המשתמש עדיין מנוי ומקבל את ההטבות של המינוי. אם המשתמש מקיש על 'חידוש המינוי', הביטול למעשה מבוטל והמינוי ממשיך להתחדש. הפעולה הזו נקראת שחזור במסמכי התיעוד ובממשקי ה-API של Play למפתחים.
אחרי שמינוי שמתחדש אוטומטית פג, אתם יכולים לאפשר למשתמשים לרכוש את אותו מינוי בסיסי. הפעולה הזו נקראת resubscribe (חידוש המינוי) במסמכי התיעוד ובממשקי ה-API של Play למפתחים. אפשר להגדיר את האפשרות הזו לכל תוכנית בסיס ב-Play Console או באמצעות API.
שחזור לפני התפוגה
אם האפליקציה מסתמכת רק על השיטה
queryPurchasesAsync()
כדי לקבוע אם למשתמש יש זכאות למינוי, האפליקציה צריכה לטפל בשחזורים באופן אוטומטי, כי השיטה queryPurchasesAsync()
ממשיכה להחזיר רכישות שבוטלו לפני תאריכי התפוגה שלהן. מינוי ששוחזר ממשיך להתחדש כאילו הוא לא בוטל.
אם האפליקציה מסנכרנת את מצב המינוי עם השרת העורפי, צריך להאזין להודעה SubscriptionNotification עם הסוג SUBSCRIPTION_RESTARTED. אחרי שמקבלים את ה-RTDN הזה, האפליקציה יכולה להגיב להתראה, לתעד שהמינוי מוגדר עכשיו לחידוש ולהפסיק להציג הודעות שחזור באפליקציה. משאב המינוי נראה בערך כמו בדוגמה הבאה:
{
"kind": "androidpublisher#subscriptionPurchaseV2",
...
"subscriptionState": "SUBSCRIPTION_STATE_ACTIVE",
...
"lineItems": [
{
"productId": "sub_variant_plan01",
"expiryTime": next_renewal_date
...
}
],
}
הרשמה מחדש אחרי שהמינוי פג
אם מינוי בסיסי שמתחדש אוטומטית מוגדר באמצעות Google Play Console או API כך שניתן להירשם מחדש, משתמשים יכולים לרכוש מחדש מינוי שפג תוקפו בחנות Google Play.
אלה רכישות חדשות. Google Play מנפיק טוקן רכישה חדש לגמרי, והקצה העורפי מקבל RTDN עם סוג SUBSCRIPTION_PURCHASED. סטטוס הרכישה של רכישה מחוץ לאפליקציה מהסוג הזה לא כולל linkedPurchaseToken שמשויך לרכישה המקורית במקרה כזה, כי המינוי המקורי פג לגמרי.
כדי לוודא שהמינויים שנרכשו מחדש ישויכו למשתמשים הנכונים ולמנוע החזרים כספיים אוטומטיים על רכישות שלא אושרו, אתם צריכים לאשר את הרכישה מחדש בשרת הבק-אנד:
מתקשרים אל
purchases.subscriptionsv2.getעם אסימון הרכישה החדש מ-RTDN. התשובה לרכישה מסוג זה מחוץ לאפליקציה כוללת את השדהoutOfAppPurchaseContext, שמופיע רק ברכישות של הרשמה מחדש שלא אושרו. בשדה הזה מציינים:-
expiredExternalAccountIdentifiers: אובייקטExternalAccountIdentifiersשמכיל את השדותobfuscatedAccountIdו-obfuscatedProfileIdשהוגדרו למינוי הקודם שפג תוקפו, אם הם הוגדרו. -
expiredPurchaseToken: אסימון הרכישה של המינוי האחרון שתוקפו פג.
אפשר להשתמש באחד מהמזהים האלה כדי לחפש את הרכישה החדשה ולקשר אותה לחשבון המשתמש הנכון בקצה העורפי.
-
כדי לאשר את הרכישה, צריך להתקשר אל
purchases.subscriptions.acknowledge.- אופציונלית, אתם יכולים לשלוח את
obfuscatedAccountIdו-obfuscatedProfileIdשל המשתמש אם הגדרתם אותם באמצעותsetObfuscatedAccountIdו-setObfuscatedProfileIdבמהלך רצף פעולות החיוב מתוך האפליקציה.
- אופציונלית, אתם יכולים לשלוח את
הגישה הזו בצד השרת מאפשרת לכם לאשר את הרכישה תוך שלושה ימים מתאריך הרכישה, גם אם המשתמש לא פותח את האפליקציה.
שדרוגים, שדרוגים לאחור וחידוש מינוי
כשמשתמש משדרג, משנמך או נרשם מחדש אחרי ביטול המינוי באפליקציה לפני שהוא פג, המינוי הישן הופך ללא תקף ונוצר מינוי חדש עם טוקן רכישה חדש.
בנוסף, משאב המינוי שמוחזר מממשק API של Google Play למפתחים מכיל את השדה linkedPurchaseToken שמציין את הרכישה הישנה שממנה המשתמש שדרג, שנמך או נרשם מחדש. אפשר להשתמש באסימון הרכישה בשדה הזה כדי לחפש את המינוי הישן ולזהות את חשבון המשתמש הקיים, וכך לשייך את הרכישה החדשה לאותו חשבון.
לפני שמציעים למשתמש באפליקציה אפשרויות לשדרוג, לנמוך או לחידוש המינוי, צריך לאשר את המינוי הקיים. כל שינוי בתוכנית או חידוש מינוי ייחסמו אם המינוי הקיים עדיין בהמתנה לאישור.
אם המשתמש רוכש בהצלחה שדרוג, החלפת מינוי למינוי זול יותר או מינוי מחדש, זוהי רכישה חדשה שאתם צריכים לאשר. הדרך המומלצת לעשות זאת היא באמצעות ממשק API של Google Play למפתחים. משאב המינוי אמור להיראות כך:
{
"kind": "androidpublisher#subscriptionPurchaseV2",
...
"subscriptionState": "SUBSCRIPTION_STATE_ACTIVE",
"linkedPurchaseToken": old_purchase_token,
...
"lineItems": [
{
"productId": "sub_variant_plan01",
"expiryTime": next_renewal_date,
"autoRenewingPlan": {
"autoRenewEnabled": true
}
}
],
}
שינויים במחירים
במדריך לשינוי מחירים אפשר לקרוא על שינוי מחירים של מינויים שמתחדשים אוטומטית ועל עדכון המשתמשים כשצריך.
כשמוסיפים שינוי במחיר וכשיש עדכונים בסטטוס של השינוי במחיר, תקבלו את ה-RTDN SUBSCRIPTION_PRICE_CHANGE_UPDATED. אפשר לשלוח שאילתה לנקודת הקצה purchases.subscriptionsv2.get כדי לקבל משאב מינוי שיכיל פרטים על שינוי המחיר של כל פריט במינוי.
כששינויי מחיר חלים על מנויים קיימים כהסכמה, תקבלו הודעת RTDN אם המשתמש יאשר או ידחה את המחיר החדש.
איך מטפלים באישור של המשתמשים לשינוי במחיר
כשמשתמש מאשר את העלייה במחיר המינוי, אתם מקבלים הודעה מסוג SubscriptionNotification עם הערך SUBSCRIPTION_PRICE_CHANGE_UPDATED.
טיפול בחידושים אחרי החלת שינוי במחיר
אם המחיר של המינוי ירד או אם המינוי יחודש אחרי עלייה במחיר, תקבלו הודעה מסוג SUBSCRIPTION_RENEWED עם הערך SubscriptionNotification. התייחסו להתראה הזו כמו לכל חידוש אחר.
טיפול במקרים שבהם המשתמש לא מסכים להעלאת מחיר
אם משתמש לא אישר את העלאת המחיר לפני שהמינוי שלו מתחדש במחיר הגבוה יותר, המינוי שלו יבוטל באופן אוטומטי ותקבלו הודעת SubscriptionNotification עם הערך SUBSCRIPTION_CANCELED בשדה type. מטפלים באירוע הזה כמו שמתואר בקטע ביטולים.
באותו אופן, משתמשים יכולים לבטל את המינויים שלהם אם חלה העלאת מחיר עם אפשרות לסירוב.
הסכמה להעלאת מחיר (רלוונטי רק באזור קוריאה)
בעקבות תקנות חדשות בקוריאה הדרומית (KR), משתמשי מינוי באזור KR חייבים להביע הסכמה לכל עליית מחיר שתתרחש לאחר סיום תקופת הניסיון בחינם או תקופת ההיכרות שלהם.
כדי לעזור לכם לעמוד בדרישות הרגולציה, מערכת Play תודיע למשתמשים באזור קוריאה על הדרישה לקבלת הסכמה, ותאחסן את תשובת המשתמשים בנוגע להסכמה. המינויים של משתמשים שלא יביעו הסכמה לפני שהמחיר הגבוה יותר ייכנס לתוקף יבוטלו באופן אוטומטי. בנוסף להתראות שנשלחות מ-Play, אתם יכולים לשלוח למשתמשים התראות מותאמות אישית על העלאת מחירים, ולספק בהתראות קישור לדף ניהול ספציפי.
כשתקופת ההסכמה מתחילה או כשהמשתמש מספק הסכמה, תקבלו הודעה מסוג SubscriptionNotification עם הערך SUBSCRIPTION_PRICE_STEP_UP_CONSENT_UPDATED.
ההבדל בין העלאת מחיר לבין שינוי מחיר
price step-up מתייחס לעלייה במחיר המינוי, בגלל מעבר משלב אחד של המינוי לשלב אחר. לדוגמה, מינוי שעובר מתקופת ניסיון בחינם למחיר רגיל. אפשר להשתמש בשדה offerPhase במשאב המינוי כדי לזהות את השלב הנוכחי של המינוי.
עם זאת, price change מתייחס לעדכוני מחירים שאתם (המפתחים) יוזמים עבור המחיר של המינוי הבסיסי. לדוגמה,
העלאת מחיר בכפוף להסכמה או העלאת מחיר עם אפשרות לסירוב.
ניהול מחזור החיים של מינויים בתשלום מראש
בדומה למינויים שמתחדשים אוטומטית, צריך לאשר תוכניות בתשלום מראש אחרי כל רכישה חדשה. במקרה של מינויים בתשלום מראש, אתם צריכים לעבד באופן מלא את הרכישה הראשונית ואת כל הטעינות, כי המשתמש צריך לעבור את תהליך הרכישה בכל פעם.
בגלל האפשרות לפרקי זמן קצרים של תוכניות בתשלום מראש, חשוב לאשר את הרכישה בהקדם האפשרי. צריך לאשר תוכניות בתשלום מראש עם משך של שבוע אחד או יותר תוך 3 ימים. בתוכניות בתשלום מראש עם משך שימוש של פחות משבוע, צריך לאשר את התוכנית תוך מחצית ממשך השימוש. לדוגמה, למפתחים יש יום וחצי לאשר רכישה של מינוי בתשלום מראש ל-3 ימים.
הודעה מסוג SubscriptionNotification עם הערך SUBSCRIPTION_PURCHASED נשלחת ללקוח ה-RTDN בכל פעם שנרכש מינוי לתוכנית בתשלום מראש, כולל כל טעינה. מפעילים את השיטה purchases.subscriptionsv2.get כדי לבדוק את הסטטוס העדכני של המינוי לתוכנית בתשלום מראש.
טוקן רכישה חדש מונפק לרכישות של טעינת יתרה, ואתם מקבלים את טוקן הרכישה הקודם בשדה linkedPurchaseToken כחלק ממצב הרכישה החדש של המינוי. אסימון הרכישה תקף ממועד ההרשמה למינוי ועד 60 יום אחרי תאריך התפוגה. אחרי התאריך הזה, אי אפשר יותר להשתמש בטוקן הרכישה כדי להפעיל את ממשק API של Google Play למפתחים.
משאב המינוי לרכישה של תוכנית בתשלום מראש נראה דומה לדוגמה הבאה:
{
"kind": "androidpublisher#subscriptionPurchaseV2",
"startTime": "2022-04-22T18:39:58.270Z",
"regionCode": "US",
"subscriptionState": "SUBSCRIPTION_STATE_ACTIVE",
"latestOrderId": "GPA.3333-4137-0319-36762",
"acknowledgementState": "ACKNOWLEDGEMENT_STATE_ACKNOWLEDGED",
"lineItems": [
{
"productId": "prepaid_plan01",
"expiryTime": expiry_date,
"prepaidPlan": {
"allowExtendAfterTime": timestamp_after_which_topups_are_allowed
}
}
]
}
בשדה expiryTime אפשר לראות מתי מסתיימת הזכאות. רכישות של טעינת יתרה מאריכות את משך המינוי על ידי צבירה של זמן. המשמעות היא שאם המשתמש מוסיף כסף לפני שתוקף הזכאות המקורית שלו מסתיים, הזמן החדש מתווסף לתאריך התפוגה הקודם.
אפשר להציג באפליקציה הודעה שמודיעה למשתמשים שאפשר להאריך את המינויים שלהם בתשלום מראש באמצעות טעינת יתרה. כדי לדעת מתי משתמש יוכל להוסיף כסף ליתרה, בודקים את השדה allowExtendAfterTime במשאב המינוי.
מינויים בתשלום מראש לא מתחדשים אוטומטית, ולכן אי אפשר לבטל אותם. אם משתמש רוצה לבטל תוכנית בתשלום מראש, הוא יכול לחכות עד שתגיע לתאריך התפוגה שלה.
שדות של 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מגרסאות קודמות.