מחזור החיים של מינוי

רכישות של מינויים יכולות לעבור כמה מצבים שונים במהלך מחזור החיים שלהן, בהתאם להרבה גורמים, כולל התנהגות החידוש האוטומטי, מצבים של דחיית תשלום ופעולות ניהול של המפתח.

ניהול מחזור החיים של מינויים שמתחדשים אוטומטית

כשסטטוס המינוי של משתמש משתנה, שרת הקצה העורפי מקבל הודעת SubscriptionNotification.

subs-auto-renew-state
איור 1. מצבים במחזור החיים ואירועי מעבר לרכישות של מינויים עם חידוש אוטומטי.

כדי לעדכן את הסטטוס בשרת העורפי, קוראים ל-API‏ purchases.subscriptionsv2.get עם טוקן הרכישה שכלול בהתראה. נקודת הקצה הזו מספקת את המצב העדכני של המנוי בהינתן טוקן רכישה, והיא נחשבת למקור האמת לניהול מנויים.

אסימון הרכישה תקף ממועד ההרשמה למינוי ועד 60 יום אחרי תאריך התפוגה. אחרי התאריך הזה, אי אפשר יותר להשתמש בטוקן הרכישה כדי לבצע קריאה ל-Google Play Developer API.

רכישות חדשות של מינויים שמתחדשים אוטומטית

כשמשתמש רוכש מינוי, נשלחת ללקוח ה-RTDN שלכם הודעה מסוג SubscriptionNotification עם הערך SUBSCRIPTION_PURCHASED. בין אם קיבלתם את ההתראה הזו או רשמתם רכישה חדשה מתוך האפליקציה באמצעות PurchasesUpdatedListener או אחזור ידני של רכישות בשיטה onResume() של האפליקציה, עליכם לעבד את הרכישה החדשה בקצה העורפי המאובטח שלכם. לשם כך, בצע את הצעדים הבאים:

  1. שולחים שאילתה לנקודת הקצה purchases.subscriptionsv2.get כדי לקבל משאב של מינוי שמכיל את הסטטוס העדכני של המינוי.
  2. מוודאים שהערך של השדה subscriptionState הוא SUBSCRIPTION_STATE_ACTIVE.
  3. מאמתים את הרכישה.
  4. נותנים למשתמש גישה לתוכן. אפשר לזהות את חשבון המשתמש שמשויך לרכישה באמצעות האובייקט ExternalAccountIdentifiers ממקור המידע של המינוי, אם המזהים הוגדרו בזמן הרכישה באמצעות setObfuscatedAccountId ו-setObfuscatedProfileId.

ספריית החיוב של 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
      }
    }
  ],
}

חידושים של מינויים

במינויים שמתחדשים אוטומטית ושלא משלמים עליהם בתשלומים, תישלח הודעה כשהמינוי יתחדש.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
      }
    }
  ]
}

אין צורך לאשר חידוש מינויים.

תקופת חסד

אם יש בעיות בתשלום על חידוש מינוי, Google מודיעה למשתמש ומנסה לחדש את המינוי מדי פעם למשך זמן מסוים לפני שהמינוי יפוג. תקופת השחזור יכולה לכלול תקופת חסד ואחריה תקופת השהיית החשבון. במהלך תקופת החסד, למשתמש עדיין צריכה להיות גישה לזכאות שלו למינוי.

השיטה queryPurchasesAsync() ממשיכה להחזיר רכישות שנמצאות בתקופת החסד. אם האפליקציה שלך מסתמכת רק על queryPurchasesAsync כדי לבדוק אם למשתמש יש זכאות למינוי, האפליקציה צריכה לטפל אוטומטית בתקופות החסד, כי המינויים האלה מוצגים כפעילים דרך ספריית החיובים ב-Play.

סנכרון של מצב המינוי עם השרת העורפי מאפשר לכם לקבל מידע על דחיות תשלום, ונותן לכם יותר הקשר כשאתם מנסים להפחית את הנטישה הלא רצונית. האזנה להודעות SubscriptionNotification עם הסוג SUBSCRIPTION_IN_GRACE_PERIOD כדי לקבל התראה כשהמשתמש נכנס לתקופת חסד. בזמן שהמשתמש נמצא בתקופת חסד, משאב המינוי מכיל את הערך 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 Store. כשמשתמש נכנס לתקופת חסד, כדאי לעודד אותו לתקן את אמצעי התשלום שלו, למקרה שהכישלון לא היה מכוון. דרך פשוטה לעשות את זה היא באמצעות ה-API של הודעות בתוך האפליקציה. אם קוראים ל-API הזה כשהמשתמש פותח את האפליקציה, מוצגת לו הודעה זמנית ב-Play, שמיידעת אותו שהתשלום שלו נדחה. ההודעה כוללת גם קישור עומק שדרכו המשתמש יכול לתקן את אמצעי התשלום שלו ב-Google Play.

ברגע שהמשתמש יתקן את אמצעי התשלום, המינוי יחודש בתאריך החידוש המקורי, ותוכלו לטפל בחידוש כמו שמתואר בקטע חידושים.

אם המשתמש לא יתקן את אמצעי התשלום במהלך תקופת החסד, המינוי יעבור להשהיית חשבון והמשתמש יאבד את הזכאות.

גישה לחשבון ושחזור שלו בתקופת החסד

איור 2 מציג ציר זמן של מינוי שנכנס לתקופת חסד ואז חוזר לפעולה אחרי שהמשתמש מתקן את אמצעי התשלום. בתום תקופת החסד, המשתמש יאבד את ההטבות של המינוי והחשבון שלו יועבר למצב של השהיית חשבון.

איור 2. ציר זמן של מינוי שנכנס לתקופת חסד וחוזר לפעילות לפני שהיא מסתיימת.

חשוב לזכור את הנקודות הבאות:

  • במהלך תקופת החסד, הגישה של המשתמש להטבות המינוי לא אמורה להיפסק.
  • כשמינוי משוחזר במהלך תקופת החסד, תאריך החידוש לא מתאפס.
  • אם תאריכו את תקופת החסד – למשל מ-7 ימים ל-14 ימים – המשתמשים שנמצאים בתקופת חסד יקבלו גישה מורחבת להטבות המינוי.
  • אם תקצרו את תקופת החסד, ההטבות של המינוי של משתמשים שנמצאים בשלב מתקדם מספיק בתקופת החסד הקודמת כך שהם חורגים מתקופת החסד החדשה יבוטלו באופן מיידי. לדוגמה, אם תקצרו את תקופת החסד מ-14 יום ל-7 ימים, ההטבות של המינוי של משתמשים שנמצאים בימים 8 עד 14 של תקופת החסד הקודמת יבוטלו באופן מיידי.
  • המינוי נשאר פעיל ולא תקבלו הודעה על תקופת חסד עד שתקופת החסד השקטה תסתיים

תקופת חסד שקטה

אפשר להגדיר תקופת חסד של 0 ימים, אבל מערכת Play תמתין לפחות יום אחד כדי לוודא שיש מספיק זמן לניסיונות חוזרים של תשלום. תקופת החסד השקטה הזו מספקת רשת ביטחון לעיבוד התשלומים. במהלך 24 השעות האלה, המינוי נשאר בסטטוס ACTIVE.

הדרך הכי טובה להתעדכן בשינויים בסטטוס המינוי היא להאזין להתראות בזמן אמת למפתחים (RTDN) ולפעול בהתאם. כדי לקבל סטטוס מדויק יותר של המינוי, כדאי להתקשר לשיטה purchases.subscriptionsv2.get() בזמן ה-RTDN ולא בזמן התפוגה.

בהתאם לסטטוס המינוי אחרי תקופת החסד השקטה של 24 שעות, תקבלו אחת מההתראות הבאות:

  • SUBSCRIPTION_ON_HOLD (אם התכונה הופעלה)
  • SUBSCRIPTION_CANCELED (אם בוטלה)
  • ‫SUBSCRIPTION_EXPIRED (if expired)
  • ‫SUBSCRIPTION_RENEWED (if successfully renewed)

אפשר גם להפעיל את השיטה subscriptionV2.get() בכל שלב אחרי תקופת החסד השקטה של 24 שעות כדי לקבל את הסטטוס העדכני של המינוי.

השהיית החשבון

אם יש בעיות בתשלום על חידוש מינוי, אחרי שתקופת החסד מסתיימת, מתחילה תקופת השהיה של החשבון. כשמינוי עובר להשהיית החשבון, צריך לחסום את הגישה להרשאה של המינוי.

במהלך ההשהיה של החשבון, צריך להמשיך לטפל בכל ביטול, שחזור או רכישה מחדש של המינויים לפי הצורך, כי יכול להיות שהמשתמש יבצע את השינויים האלה בזמן שהמינוי מושהה.

התראות בזמן אמת על ניתוקים מודיעות לכם כשהמשתמש נכנס לתקופת השהיית החשבון, כדי שתוכלו להודיע לו בהקדם האפשרי למה הגישה שלו למינוי הושעתה. דרך פשוטה לעשות את זה היא באמצעות In-App Messaging API. אם תפעילו את ה-API הזה כשהמשתמש יפתח את האפליקציה, תוצג לו הודעה בחלון קופץ זמני שתעדכן אותו שהתשלום שלו נדחה. ההודעה כוללת גם קישור עומק שמאפשר למשתמש לתקן את אמצעי התשלום שלו ב-Google Play.

אם המשתמשים יכולים לגשת לתוכן של המינוי מחוץ לאפליקציה, הם עשויים לגלות שהם איבדו את הגישה בפלטפורמות שונות. כדאי לשלוח למשתמש הודעת פוש או אימייל כדי לעדכן אותו שהמינוי שלו לא פעיל יותר בגלל דחיית התשלום.

המינוי לא מוחזר על ידי השיטה queryPurchasesAsync() במהלך השהיית החשבון, ולכן אם האפליקציה שלכם מסתמכת על השיטה הזו כדי להציג רכישות קיימות, כדאי לתמוך בהשהיית החשבון כברירת מחדל.

באמצעות התראות בזמן אמת למפתחים, תקבלו הודעת SubscriptionNotification עם סוג SUBSCRIPTION_ON_HOLD כשמינוי עובר להקפאת החשבון. מתקשרים אל השיטה 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 מציג ציר זמן של מינוי שהחשבון שלו מושהה ואז חוזר לפעילות אחרי שהמשתמש מתקן את אמצעי התשלום.

איור 3. ציר זמן של מינוי שנכנס להשהיית חשבון וחוזר לפעילות לפני שהוא מסתיים.

בדומה לדוגמה הקודמת, באיור 4 מוצג ציר זמן של מינוי שנכנס לתקופת חסד לפני שהוא מושהה, ואז חוזר לפעולה בזמן ההשהיה.

איור 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 של משאב המינוי שמוחזר מ-Google Play Developer API מוגדר לערך SUBSCRIPTION_STATE_CANCELED, והשדה expiryTime מכיל את התאריך שבו המשתמש יאבד את הגישה למינוי. אם התאריך הזה חלף, המשתמש אמור לאבד את ההרשאה באופן מיידי. לדוגמה, זה יכול לקרות אם משתמש מבטל מינוי בזמן שהחשבון שלו מושהה בגלל סירוב תשלום.

משאב המינוי לרכישה שבוטלה נראה דומה לדוגמה הבאה:

{
  "kind": "androidpublisher#subscriptionPurchaseV2",
  ...
  "subscriptionState": "SUBSCRIPTION_STATE_CANCELED",
  ...
  "lineItems": [
    {
      "productId": "sub_variant_plan01",
      "expiryTime": expiration_time,
      ...
    }
  ],
}

במינויים לתשלומים, תישלח התראה על ביטול שבוצע על ידי המשתמש אם נותרו תשלומים לתקופת ההתחייבות.SUBSCRIPTION_CANCELLATION_SCHEDULED הביטול בהמתנה והוא ייכנס לתוקף בסוף תקופת ההתחייבות הנוכחית. כשמקבלים את ההתראה הזו, הערך של שדה subscriptionState במשאב המינוי שמוחזר מ-Google Play Developer API הוא SUBSCRIPTION_STATE_ACTIVE, כי המינוי לתשלומים עדיין פעיל עד לסיום תקופת ההתחייבות. עם זאת, קיים אובייקט ריק של pendingCancellation. תישלח 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(). כדאי להציג באפליקציה הודעה למשתמשים על ביטול המינוי שלהם, ולציין את תאריך התפוגה.

ביטולים

יכולות להיות סיבות שונות לביטול מינוי, כולל ביטול המינוי על ידי הקצה האחורי באמצעות purchases.subscriptionsv2.revoke או ביטול החיוב על הרכישה. במצב כזה, צריך לבטל את ההרשאה של המשתמש באופן מיידי. כשזה קורה, נשלחת הודעת SubscriptionNotification עם הסוג SUBSCRIPTION_REVOKED. כשמקבלים את ההתראה הזו, השדה subscriptionState של משאב המינוי שמוחזר מ-Google Play Developer API מוגדר לערך SUBSCRIPTION_STATE_EXPIRED.

משאב המינוי של רכישה שבוטלה נראה דומה לדוגמה הבאה:

{
  "kind": "androidpublisher#subscriptionPurchaseV2",
  ...
  "subscriptionState": "SUBSCRIPTION_STATE_EXPIRED",
  ...
  "lineItems": [
    {
      "productId": "sub_variant_plan01",
      "expiryTime": expiration_time,
      ...
    }
  ]
}

מינויים שנדחו

יכולות להיות מגוון סיבות לכך שתרצו להאריך את זכויות הגישה של משתמש. לדוגמה, יכול להיות שתרצו להציע למשתמשים גישה חינמית כקידום מכירות מיוחד, כמו שבוע חינם ברכישת סרט או גישה חינמית ללקוחות כמחווה של רצון טוב. אפשר להשתמש בשיטה purchases.subscriptions.defer מ-Play Developer API כדי להקדים את תאריך החיוב הבא של מינוי עם חידוש אוטומטי. כשעושים את זה, נשלחת הודעה מסוג SUBSCRIPTION_DEFERRED עם הערך SubscriptionNotification. במהלך תקופת הדחייה, המשתמש נרשם לתוכן שלכם עם גישה מלאה, אבל לא מחויב. תאריך חידוש המינוי מתעדכן בהתאם לתאריך החדש.

במינויים בתשלום מראש, אפשר להשתמש ב-API לדחיית החיוב כדי לדחות את מועד התפוגה.

משאב המינוי למינוי שנדחה נראה כך:

{
  "kind": "androidpublisher#subscriptionPurchaseV2",
  ...
  "subscriptionState": "SUBSCRIPTION_STATE_ACTIVE",
  ...
  "lineItems": [
    {
      "productId": "sub_variant_plan01",
      "expiryTime": timestamp_in_future,
      ...
    }
  ],
}

מינויים שהושהו

כדי להפחית נטישה מכוונת, אפשר לאפשר למשתמשים להשהות את המינוי. כשמפעילים את תכונת ההשהיה, המשתמשים יכולים להשהות את המינוי לתקופה של שבוע עד שלושה חודשים, בהתאם לתקופה החוזרת. הפעולה הזו תשעה את המינוי באופן זמני.

מחזור חיוב של מינוי שבועי חודשי לשלושה חודשים לשישה חודשים שנתי
משך ההשהיה האפשרי* שבוע אחד
שבועיים
3 שבועות
4 שבועות		 חודש אחד
2 חודשים
3 חודשים		 חודש אחד
2 חודשים
3 חודשים		 חודש אחד
2 חודשים
3 חודשים		 לא רלוונטי
*המחירים עשויים להשתנות בכל שלב.

ההשהיה של המינוי מתחילה רק אחרי שתקופת החיוב הנוכחית מסתיימת. בזמן שהמינוי מושהה, למשתמש אין גישה למינוי והוא לא משלם את מחיר החידוש. בסיום תקופת ההשהיה, המינוי יחודש ו-Google תנסה לחדש אותו. אם החידוש יתבצע בלי בעיות, המינוי יחזור להיות פעיל. אם החידוש נכשל בגלל בעיה בתשלום, המשתמש עובר למצב של השהיית החשבון, כמו שמוצג באיורים 5 ו-6:

איור 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.

הודעה מסוג SUBSCRIPTION_RECOVERED עם הערך SubscriptionNotification נשלחת אם המינוי מתחדש אוטומטית בסיום תקופת ההשהיה, או אם המשתמש בחר לחדש את המינוי באופן ידני.

הודעה מסוג SubscriptionNotification עם סוג SUBSCRIPTION_ON_HOLD נשלחת אם הייתה בעיה בתשלום במהלך הניסיון לחדש את המינוי אחרי השהיה.

בשני המקרים צריך לפעול לפי ההוראות שמופיעות במאמר בנושא השעיית חשבון.

הרשמה מחדש

במינויים בסיסיים שמתחדשים אוטומטית, יכול להיות שיוצג בחנות Google Play לחצן הרשמה מחדש. הכפתור הזה מאפשר למשתמשים לקבל שוב גישה למינוי. יכולות להיות סיבות שונות לכך שהיא לא תופיע, למשל אם התוקף של המינוי פג לפני זמן רב.

איור 7. בקטע 'חשבון' > 'מינויים' באפליקציית חנות Google Play מוצג מינוי שבוטל עם לחצן הרשמה מחדש.

הכיתוב על הלחצן הוא תמיד הרשמה מחדש, אבל הפונקציונליות שלו תלויה בסטטוס המינוי.

אם מינוי בוטל אבל עדיין לא פג התוקף שלו, המשתמש עדיין מנוי ומקבל את ההטבות של המינוי. אם המשתמש מקיש על 'חידוש המינוי', הביטול מבוטל והמינוי ממשיך להתחדש. הפעולה הזו נקראת שחזור במסמכי התיעוד ובממשקי ה-API של Play למפתחים.

אחרי שמינוי שמתחדש אוטומטית פג, אתם יכולים לאפשר למשתמשים לרכוש את אותו מינוי בסיסי. הפעולה הזו נקראת חידוש המינוי במסמכי התיעוד ובממשקי ה-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 Store.

אלה רכישות חדשות. ‫Google Play מנפיק טוקן רכישה חדש לגמרי, והקצה העורפי מקבל RTDN עם סוג SUBSCRIPTION_PURCHASED. סטטוס הרכישה של רכישה מחוץ לאפליקציה מסוג כזה לא כולל linkedPurchaseToken שמשויך לרכישה המקורית במקרה הזה, כי המינוי המקורי פג לגמרי.

כדי לוודא שהמינויים שנרכשו מחדש ישויכו למשתמשים בצורה מדויקת ולמנוע החזרים כספיים אוטומטיים על רכישות שלא אושרו, אתם צריכים לאשר את הרכישה מחדש בשרת הבק-אנד:

  1. מתקשרים אל purchases.subscriptionsv2.get עם אסימון הרכישה החדש מ-RTDN. התשובה לרכישה מסוג זה מחוץ לאפליקציה כוללת את השדה outOfAppPurchaseContext, שמופיע רק ברכישות של מינויים שלא אושרו. בשדה הזה מציינים:

    • ‫expiredExternalAccountIdentifiers: אובייקט ExternalAccountIdentifiers שמכיל את השדות obfuscatedAccountId ו-obfuscatedProfileId שהוגדרו למינוי הקודם שפג תוקפו, אם הם הוגדרו.
    • ‫expiredPurchaseToken: אסימון הרכישה של המינוי האחרון שתוקפו פג.

    אפשר להשתמש באחד מהמזהים האלה כדי לחפש את הרכישה החדשה ולקשר אותה לחשבון המשתמש הנכון בקצה העורפי.

  2. כדאי להתקשר אל purchases.subscriptions.acknowledge כדי לאשר את הרכישה.

    • אפשר גם לשלוח את obfuscatedAccountId וobfuscatedProfileId של המשתמש אם הגדרתם אותם באמצעות setObfuscatedAccountId ו-setObfuscatedProfileId במהלך תהליך החיוב מתוך האפליקציה.

הגישה הזו בצד השרת מאפשרת לכם לאשר את הרכישה תוך שלושה ימים מתאריך הרכישה, גם אם המשתמש לא פותח את האפליקציה.

שדרוגים, שדרוגים לאחור וחידוש מינוי

כשמשתמש משדרג, מוריד את רמת המינוי או נרשם אחרי ביטול המינוי באפליקציה לפני שתוקף המינוי מסתיים, המינוי הישן הופך ללא תקף ונוצר מינוי חדש עם טוקן רכישה חדש.

בנוסף, משאב המינוי שמוחזר מ-Google Play Developer API מכיל שדה linkedPurchaseToken שמציין את הרכישה הקודמת שממנה המשתמש שדרג, הוריד את רמת המינוי או נרשם מחדש. אפשר להשתמש באסימון הרכישה בשדה הזה כדי לחפש את המינוי הישן ולזהות את חשבון המשתמש הקיים, וכך לשייך את הרכישה החדשה לאותו חשבון.

לפני שמציעים למשתמש באפליקציה אפשרויות לשדרוג, לנמוך או לחידוש המינוי, צריך לאשר את המינוי הקיים. כל שינוי בתוכנית או חידוש מינוי נחסמים אם המינוי הקיים עדיין ממתין לאישור.

אם המשתמש רוכש בהצלחה שדרוג, החלפת מינוי למינוי זול יותר או מינוי מחדש, זו רכישה חדשה שצריך לאשר. הדרך המומלצת לעשות זאת היא באמצעות Google Play Developer API. משאב המינוי אמור להיראות כך:

{
  "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 מתייחס לעלייה במחיר המינוי, בגלל מעבר משלב אחד של המינוי לשלב אחר. לדוגמה, מינוי שעובר מתקופת ניסיון בחינם למחיר רגיל.

עם זאת, price change מתייחס לעדכוני מחירים שאתם (המפתחים) יוזמים לגבי המחיר של המינוי הבסיסי. לדוגמה, העלאת מחיר בכפוף להסכמה או העלאת מחיר עם אפשרות לסירוב.

ניהול מחזור החיים של מינויים בתשלום מראש

בדומה למינויים שמתחדשים אוטומטית, אתם צריכים לאשר תוכניות בתשלום מראש אחרי כל רכישה חדשה. במקרה של מינויים בתשלום מראש, אתם צריכים לעבד באופן מלא את הרכישה הראשונית ואת כל הטעינות, כי המשתמש צריך לעבור את תהליך הרכישה בכל פעם.

בגלל האפשרות לפרקי זמן קצרים של תוכניות בתשלום מראש, חשוב לאשר את הרכישה בהקדם האפשרי. צריך לאשר תוכניות בתשלום מראש עם משך שימוש של שבוע אחד או יותר תוך 3 ימים. בתוכניות בתשלום מראש עם משך שימוש של פחות משבוע, צריך לאשר את התוכנית תוך מחצית ממשך השימוש. לדוגמה, למפתחים יש יום וחצי לאשר רכישה של מינוי בתשלום מראש ל-3 ימים.

איור 8. מצבים במחזור החיים ואירועי מעבר לרכישות של מינויים.

הודעה מסוג SUBSCRIPTION_PURCHASED עם SubscriptionNotification נשלחת ללקוח ה-RTDN שלכם בכל פעם שרוכשים מינוי לתוכנית בתשלום מראש, כולל כל טעינה. כדי לבדוק את הסטטוס העדכני של המינוי לתוכנית בתשלום מראש, מפעילים את השיטה purchases.subscriptionsv2.get.

טוקן רכישה חדש מונפק לרכישות של טעינת יתרה, ואתם מקבלים את טוקן הרכישה הקודם בשדה linkedPurchaseToken כחלק ממצב הרכישה החדש של המינוי. אסימון הרכישה תקף ממועד ההרשמה למינוי ועד 60 יום אחרי תאריך התפוגה. אחרי התאריך הזה, אי אפשר יותר להשתמש בטוקן הרכישה כדי להפעיל את 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": "prepaid_plan01",
      "expiryTime": expiry_date,
      "prepaidPlan": {
        "allowExtendAfterTime": timestamp_after_which_topups_are_allowed
      }
    }
  ]
}

בשדה expiryTime אפשר לראות מתי מסתיימת הזכאות. רכישות של טעינת יתרה מאריכות את משך המינוי על ידי צבירה של זמן. המשמעות היא שאם המשתמש מוסיף כסף לפני שתפוג הזכאות המקורית שלו, הזמן החדש יתווסף לתאריך התפוגה הקודם.

אפשר להציג באפליקציה הודעה שמודיעה למשתמשים שאפשר להאריך את המינויים שלהם בתשלום מראש באמצעות טעינת יתרה. כדי לדעת מתי משתמש יוכל להוסיף כסף ליתרה, בודקים את השדה allowExtendAfterTime במשאב המינוי.

מינויים בתשלום מראש לא מתחדשים אוטומטית, ולכן אי אפשר לבטל אותם. אם משתמש רוצה לבטל תוכנית בתשלום מראש, הוא יכול לחכות עד שתגיע לתאריך התפוגה שלה.

שדות של SubscriptionPurchaseV2 למינויים בתשלום מראש

נוספו שדות חדשים לתמיכה במינויים בתשלום מראש, שהמשתמש מאריך אותם במקום שהם יתחדשו אוטומטית. כל השדות רלוונטיים למינויים בתשלום מראש בדיוק כמו למינויים שמתחדשים אוטומטית, למעט המקרים הבאים:

  • ‫[New field] lineItems[0].prepaid_plan.allowExtendAfterTime: מציין מתי למשתמש תהיה אפשרות לקנות טעינה נוספת כדי להאריך את התוכנית שלו בתשלום מראש, כי למשתמש מותר להשתמש רק בטעינה אחת שלא נוצלה בכל פעם.
  • ‫[New field] SubscriptionState: מציין את מצב אובייקט המינוי. במינויים בתשלום מראש, הערך הזה תמיד יהיה ACTIVE, PENDING או CANCELED.
  • ‫lineItems[0].expiryTime: השדה הזה תמיד מופיע בתוכניות בתשלום מראש.
  • ‫paused_state_context: השדה הזה אף פעם לא מופיע, כי אי אפשר להשהות תוכניות בתשלום מראש.
  • ‫lineItems[0].auto_renewing_plan: לא מופיע במינויים בתשלום מראש.
  • ‫canceled_state_context: לא מופיע בתוכניות בתשלום מראש, כי השדה הזה רלוונטי רק למשתמשים שמבטלים מינוי פעיל.
  • ‫lineItems[0].productId: השדה הזה מחליף את subscriptionId מגרסאות קודמות.