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

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

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

כשמצב המינוי של משתמש משתנה, שרת הבק-אנד מקבל הודעת SubscriptionNotification.

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

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

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

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

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

  1. שולחים שאילתה לנקודת הקצה (endpoint) purchases.subscriptionsv2.get כדי לקבל משאב מינוי שמכיל את מצב המינוי העדכני.
  2. מוודאים שהערך של השדה subscriptionState הוא SUBSCRIPTION_STATE_ACTIVE.
  3. מאמתים את הרכישה.
  4. נותנים למשתמש גישה לתוכן. אפשר לזהות את חשבון המשתמש שמשויך לרכישה באמצעות האובייקט 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 שסופק במשאב המינוי שהוחזר מממשק ה-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": "sub_variant_plan01",
      "expiryTime": next_renewal_date,
      "autoRenewingPlan": {
        "autoRenewEnabled": true
      },
      "offerPhase": {
        "basePrice": {}
      }
    }
  ]
}

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

תקופת חסד

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

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

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

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

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

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

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

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

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

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

  • ‫SUBSCRIPTION_ON_HOLD (אם מופעל)
  • ‫SUBSCRIPTION_CANCELED (אם בוטל)
  • ‫SUBSCRIPTION_EXPIRED (אם פג התוקף)
  • ‫SUBSCRIPTION_RENEWED (אם החידוש בוצע בהצלחה)

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

השהיית חשבון

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

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

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

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

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

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

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

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

זמני תפוגה

כשהמינוי מסתיים, הגישה של המשתמש למינוי אמורה להיחסם. במקרה כזה, נשלחת הודעת SubscriptionNotification עם הסוג SUBSCRIPTION_EXPIRED. כשמקבלים את ההתראה הזו, שולחים שאילתה ל-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_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,
      ...
    }
  ]
}

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

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

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

כשדוחים מינוי, נשלחת הודעה מסוג 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 חודשים		 חודש
חודשיים
3 חודשים
‫*המחירים עשויים להשתנות בכל שלב.

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

איור 5. משתמש משהה את המינוי ואז מחדש אותו.
איור 6. משתמש משהה את המינוי שלו ואז החשבון שלו מושהה.

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

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

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

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

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

הרשמה מחדש

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

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

הרשמה מחדש אחרי שהמינוי פג

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

איך מטפלים בחידושים אחרי שמחילים שינוי במחיר

אם המחיר יורד, או כשהמינוי מתחדש במחיר הגבוה יותר, תקבלו הודעת SubscriptionNotification מסוג SUBSCRIPTION_RENEWED. התייחסו להתראה הזו כמו לכל חידוש אחר.

טיפול במקרים שבהם המשתמש לא מסכים להעלאת מחיר בכפוף להסכמה

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

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

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

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

כשתקופת ההסכמה תתחיל או כשהמשתמש ייתן הסכמה, תקבלו הודעת SubscriptionNotification מסוג SUBSCRIPTION_PRICE_STEP_UP_CONSENT_UPDATED.

ההבדל בין עליית מחיר לבין שינוי מחיר

price step-up מתייחס לעלייה במחיר המינוי, בגלל מעבר משלב אחד במבצע לשלב אחר. לדוגמה, מינוי שעובר מתקופת ניסיון בחינם למחיר רגיל. אתם יכולים להשתמש בשדה offerPhase במשאב המינוי כדי לזהות את השלב הנוכחי של המינוי.

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

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

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

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

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

הודעת 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 למינויים בתשלום מראש

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

  • [שדה חדש] 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 מגרסאות קודמות.