Reminder: By Aug 31, 2025, all new apps and updates to existing apps must use Billing Library version 7 or newer. If you need more time to update your app, you can request an extension until Nov 1, 2025. Learn about Play Billing Library version deprecation.

דף זה תורגם על ידי Cloud Translation API.

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

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

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

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

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

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

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

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

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

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

‫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
      }
    }
  ],
}

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

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

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

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

הרשמה מחדש

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

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

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

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

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

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

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

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

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

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

עם זאת, 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 מגרסאות קודמות.

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

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

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

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

תקופת חסד

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

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

השעיית חשבון

גישה לחשבון בהשהיה ושחזור החשבון

זמני תפוגה

ביטולים

ביטולים

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

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

הרשמה מחדש

שחזור לפני התפוגה

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

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

שינויים במחירים

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

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

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

הסכמה להעלאת מחיר (רלוונטי רק באזור KR)

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

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

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

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