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

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

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

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

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

‫Play Billing Library כוללת גם שיטה לאישור מינוי, 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 מאפשר לכם להיות מודעים יותר לדחיות תשלום, ומספק לכם יותר הקשר כשאתם מנסים להפחית את הנטישה הלא רצונית. האזנה להודעות 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. כשמשתמש נכנס לתקופת חסד, כדאי לעודד אותו לתקן את אמצעי התשלום שלו, למקרה שהכישלון לא היה מכוון. דרך פשוטה לעשות את זה היא באמצעות In-App Messaging 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 (אם התוקף פג)
  • ‫SUBSCRIPTION_RENEWED (אם החידוש יתבצע בהצלחה)

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

השהיית חשבון

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

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

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

זמני תפוגה

אחרי שמינוי מסתיים, הגישה של המשתמש למינוי אמורה להתבטל. הודעה מסוג 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_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 במקור המידע של המינוי שמוחזר מ-Google Play Developer API הוא 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 שבועות		 חודש אחד
2 חודשים
3 חודשים		 חודש אחד
2 חודשים
3 חודשים		 חודש אחד
2 חודשים
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.

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

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

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

הרשמה מחדש

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

הודעה מסוג SubscriptionNotification עם הערך SUBSCRIPTION_PURCHASED נשלחת ללקוח ה-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 מגרסאות קודמות.