REST Resource: monetization.subscriptions

משאב: מינוי

מינוי יחיד לאפליקציה.

ייצוג ב-JSON 
{
  "packageName": string,
  "productId": string,
  "basePlans": [
    {
      object (BasePlan)
    }
  ],
  "listings": [
    {
      object (SubscriptionListing)
    }
  ],
  "archived": boolean,
  "taxAndComplianceSettings": {
    object (SubscriptionTaxAndComplianceSettings)
  },
  "restrictedPaymentCountries": {
    object (RestrictedPaymentCountries)
  }
}
שדות
packageName

string

אי אפשר לשנות. שם החבילה של האפליקציה הראשית.
productId

string

אי אפשר לשנות. מזהה המוצר הייחודי של המוצר. המזהה צריך להיות ייחודי באפליקציית האב. מזהי מוצרים צריכים לכלול אותיות קטנות (a-z), ספרות (0-9), קו תחתון (_) ונקודה (.). הם צריכים להתחיל באות קטנה או בספרה, ולהיות באורך של 1 עד 40 תווים (כולל).
basePlans[]

object (BasePlan)

קבוצת המינויים הבסיסיים של המינוי הזה. מייצג את המחירים ואת משך המינוי אם לא חלים מבצעים אחרים.
listings[]

object (SubscriptionListing)

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

boolean

פלט בלבד. הוצא משימוש: אין תמיכה בארכיון של מינויים.
taxAndComplianceSettings

object (SubscriptionTaxAndComplianceSettings)

פרטים על מיסים ותאימות משפטית.
restrictedPaymentCountries

object (RestrictedPaymentCountries)

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

BasePlan

תוכנית בסיסית אחת למינוי.

ייצוג ב-JSON 
{
  "basePlanId": string,
  "state": enum (State),
  "regionalConfigs": [
    {
      object (RegionalBasePlanConfig)
    }
  ],
  "offerTags": [
    {
      object (OfferTag)
    }
  ],
  "otherRegionsConfig": {
    object (OtherRegionsBasePlanConfig)
  },

  // Union field base_plan_type can be only one of the following:
  "autoRenewingBasePlanType": {
    object (AutoRenewingBasePlanType)
  },
  "prepaidBasePlanType": {
    object (PrepaidBasePlanType)
  },
  "installmentsBasePlanType": {
    object (InstallmentsBasePlanType)
  }
  // End of list of possible types for union field base_plan_type.
}
שדות
basePlanId

string

חובה. אי אפשר לשנות. המזהה הייחודי של המינוי הבסיסי הזה. המזהה חייב להיות ייחודי במסגרת המינוי, ותואם ל-RFC-1034. כלומר, המזהה יכול להכיל רק אותיות קטנות (a-z), מספרים (0-9) ומקפים (-), והאורך המקסימלי שלו הוא 63 תווים.
state

enum (State)

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

object (RegionalBasePlanConfig)

מידע ספציפי לאזור שרלוונטי לתוכנית הבסיסית הזו.
offerTags[]

object (OfferTag)

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

object (OtherRegionsBasePlanConfig)

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

object (AutoRenewingBasePlanType)

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

object (PrepaidBasePlanType)

מגדירים מתי מינוי Base Plan לא יתחדש אוטומטית בסוף תקופת החיוב.
installmentsBasePlanType

object (InstallmentsBasePlanType)

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

מדינה (State)

המצב הנוכחי של מינוי בסיסי.

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

AutoRenewingBasePlanType

מייצג מינוי בסיסי שמתחדש אוטומטית בסוף תקופת המינוי.

ייצוג ב-JSON 
{
  "billingPeriodDuration": string,
  "gracePeriodDuration": string,
  "accountHoldDuration": string,
  "resubscribeState": enum (ResubscribeState),
  "prorationMode": enum (SubscriptionProrationMode),
  "legacyCompatible": boolean,
  "legacyCompatibleSubscriptionOfferId": string
}
שדות
billingPeriodDuration

string

חובה. אי אפשר לשנות. תקופת המינוי, בפורמט ISO 8601. רשימה של תקופות חיוב קבילות זמינה במרכז העזרה. אי אפשר לשנות את משך המינוי אחרי שיוצרים את המינוי הבסיסי.
gracePeriodDuration

string

תקופת החסד של המינוי, בפורמט ISO 8601. הערכים הקבילים צריכים להיות בימים, בין P0D לבין הערך הקטן מבין 30D ותקופת החיוב של תוכנית הבסיס.

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

המשך הכולל של תקופת החסד ותקופת השהיית החשבון צריך להיות בין P30D ל-P60D ימים, כולל.
accountHoldDuration

string

אופציונלי. תקופה מותאמת אישית להשהיית החשבון של המינוי, שצוינה בפורמט ISO 8601. הערכים הקבילים צריכים להיות בימים, בין P0D ל-P60D.

שדה ריק מייצג השהיית חשבון מומלצת, שמחושבת כ-60 ימים פחות תקופת החסד.

המשך הכולל של תקופת החסד ותקופת השהיית החשבון צריך להיות בין P30D ל-P60D ימים, כולל.
resubscribeState

enum (ResubscribeState)

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

enum (SubscriptionProrationMode)

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

boolean

אם המינוי הבסיסי המתחדש תואם לדורות קודמים.

המינוי הבסיסי שתומך בתאימות לאחור מוחזר על ידי השיטה שהוצאה משימוש querySkuDetailsAsync()‎‏, בספריית החיובים ב-Google Play.

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

string

מזהה מבצע למינוי שמתאים לגרסאות קודמות.

המבצע למינוי שתומך בתאימות לאחור מוחזר על ידי השיטה שהוצאה משימוש querySkuDetailsAsync()‎ בספריית החיובים ב-Google Play.

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

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

ResubscribeState

מצב ההרשמה מחדש של מינוי בסיסי.

טיפוסים בני מנייה (enum)
RESUBSCRIBE_STATE_UNSPECIFIED מצב לא מוגדר.
RESUBSCRIBE_STATE_ACTIVE ההרשמה מחדש פעילה.
RESUBSCRIBE_STATE_INACTIVE האפשרות 'חידוש המינוי' לא פעילה.

SubscriptionProrationMode

מצב החישוב היחסי שמשמש לחידוש מינויים בסיסיים.

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

PrepaidBasePlanType

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

ייצוג ב-JSON 
{
  "billingPeriodDuration": string,
  "timeExtension": enum (TimeExtension)
}
שדות
billingPeriodDuration

string

חובה. אי אפשר לשנות. תקופת המינוי, בפורמט ISO 8601. רשימה של תקופות חיוב קבילות זמינה במרכז העזרה. אי אפשר לשנות את משך המינוי אחרי שיוצרים את המינוי הבסיסי.
timeExtension

enum (TimeExtension)

האם המשתמשים יכולים להאריך את תוכנית הבסיס הזו שמשולמת מראש ב-Google Play. אם לא מציינים ערך, ברירת המחדל היא TIME_EXTENSION_ACTIVE.

TimeExtension

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

טיפוסים בני מנייה (enum)
TIME_EXTENSION_UNSPECIFIED מצב לא מוגדר.
TIME_EXTENSION_ACTIVE הארכת הזמן פעילה. למשתמשים מותר להוסיף כסף למינוי או להאריך את המינוי שלהם בתשלום מראש.
TIME_EXTENSION_INACTIVE הארכת הזמן לא פעילה. המשתמשים לא יכולים לחדש או להאריך את התוכנית בתשלום מראש.

InstallmentsBasePlanType

מייצג תוכנית בסיסית של תשלומים שבה המשתמש מתחייב למספר תשלומים מוגדר.

ייצוג ב-JSON 
{
  "billingPeriodDuration": string,
  "committedPaymentsCount": integer,
  "renewalType": enum (RenewalType),
  "gracePeriodDuration": string,
  "accountHoldDuration": string,
  "resubscribeState": enum (ResubscribeState),
  "prorationMode": enum (SubscriptionProrationMode)
}
שדות
billingPeriodDuration

string

חובה. אי אפשר לשנות. תקופת המינוי, בפורמט ISO 8601. רשימה של תקופות חיוב קבילות זמינה במרכז העזרה. אי אפשר לשנות את משך המינוי אחרי שיוצרים את המינוי הבסיסי.
committedPaymentsCount

integer

חובה. אי אפשר לשנות. מספר התשלומים שהמשתמש התחייב לבצע. אי אפשר לשנות אותו אחרי שיוצרים את המינוי הבסיסי.
renewalType

enum (RenewalType)

חובה. אי אפשר לשנות. סוג החידוש של מינוי בסיסי בתשלומים. המדיניות מגדירה את ההתנהגות בסיום תקופת ההתחייבות הראשונית. אי אפשר לשנות את סוג החידוש אחרי שיוצרים את מינוי Base Plan.
gracePeriodDuration

string

תקופת החסד של המינוי, בפורמט ISO 8601. הערכים הקבילים צריכים להיות בימים, בין P0D לבין הערך הקטן מבין 30D ותקופת החיוב של תוכנית הבסיס.

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

המשך הכולל של תקופת החסד ותקופת השהיית החשבון צריך להיות בין P30D ל-P60D ימים, כולל.
accountHoldDuration

string

אופציונלי. תקופה מותאמת אישית להשהיית החשבון של המינוי, שצוינה בפורמט ISO 8601. הערכים הקבילים צריכים להיות בימים, בין P0D ל-P60D.

שדה ריק מייצג השהיית חשבון מומלצת, שמחושבת כ-60 ימים פחות תקופת החסד.

המשך הכולל של תקופת החסד ותקופת השהיית החשבון צריך להיות בין P30D ל-P60D ימים, כולל.
resubscribeState

enum (ResubscribeState)

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

enum (SubscriptionProrationMode)

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

RenewalType

סוג החידוש של מינוי בסיסי בתשלומים. מגדירה את ההתנהגות בסיום תקופת ההתחייבות הראשונית. אי אפשר לשנות את סוג החידוש אחרי שיוצרים את מינוי Base Plan.

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

RegionalBasePlanConfig

הגדרות של מינוי בסיסי שספציפיות לאזור מסוים.

ייצוג ב-JSON 
{
  "regionCode": string,
  "newSubscriberAvailability": boolean,
  "price": {
    object (Money)
  }
}
שדות
regionCode

string

חובה. קוד האזור שאליו ההגדרה הזו חלה, כפי שמוגדר בתקן ISO 3166-2, למשל: US.
newSubscriberAvailability

boolean

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

object (Money)

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

OtherRegionsBasePlanConfig

פרטי תמחור למיקומים חדשים שבהם יכול להיות ש-Play יושק.

ייצוג ב-JSON 
{
  "usdPrice": {
    object (Money)
  },
  "eurPrice": {
    object (Money)
  },
  "newSubscriberAvailability": boolean
}
שדות
usdPrice

object (Money)

חובה. המחיר בדולר ארה"ב שיוצג בכל מיקום חדש שבו יושק Play.
eurPrice

object (Money)

חובה. המחיר ביורו לשימוש בכל מיקום חדש ש-Play עשויה להשיק בו.
newSubscriberAvailability

boolean

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

SubscriptionListing

המטא-נתונים של מינוי שגלויים לצרכן.

ייצוג ב-JSON 
{
  "languageCode": string,
  "title": string,
  "benefits": [
    string
  ],
  "description": string
}
שדות
languageCode

string

חובה. השפה של כרטיס המוצר הזה, כפי שמוגדרת בתקן BCP-47, למשל 'en-US'.
title

string

חובה. הכותרת של המינוי הזה בשפה של דף הפרטים הזה. טקסט פשוט.
benefits[]

string

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

string

תיאור המינוי בשפה של דף הפרטים הזה. האורך המקסימלי הוא 80 תווים. טקסט פשוט.

Methods

archive
(deprecated)

 הוצאה משימוש: אין תמיכה בארכיון של מינויים.

batchGet

 קריאה של מינוי אחד או יותר.

batchUpdate

 עדכון של קבוצת מינויים.

create

 יצירת מינוי חדש.

delete

 מחיקת מינוי.

get

 קריאת מינוי יחיד.

list

 מציגה רשימה של כל המינויים באפליקציה נתונה.

patch

 עדכון של מינוי קיים.

קודי שגיאה

הפעולות של המשאב הזה מחזירות את קודי שגיאות ה-HTTP הבאים:

קוד שגיאה סיבה תיאור רזולוציה
400 invalidValue צוין ערך לא תקין בבקשה. השגיאה הזו מוחזרת לעיתים קרובות כשפורמט טוקן הרכישה שגוי או כשהוא לא תקין. מתקנים את הערך הלא תקין של השדה בגוף הבקשה או בפרמטרים על סמך הפניה ל-API.
400 required חסר שדה או פרמטר חובה בבקשה. כדאי לעיין במסמכי התיעוד בנושא API כדי לוודא שכללתם את כל שדות החובה והפרמטרים הנדרשים.
403 userInsufficientPermission למשתמש אין מספיק הרשאות לביצוע הפעולה המבוקשת. מוודאים שלמשתמש המאומת יש את ההרשאות הנדרשות ב-Google Play Console. פרטים נוספים מופיעים במאמר בנושא שימוש בחשבון שירות.
404 notFound לא נמצא המשאב המבוקש. מוודאים שהמזהים (לדוגמה: טוקן רכישה, שם חבילה, מזהה מוצר, מזהה מינוי) נכונים.
409 concurrentUpdate היה ניסיון לעדכן אובייקט שנמצא בתהליך עדכון בו-זמני. מנסים לשלוח שוב את הבקשה עם השהיה מעריכית לפני ניסיון חוזר (exponential backoff). מומלץ להימנע משינויים בו-זמניים באותו משאב.
5xx Generic error שגיאה כללית בשרת של Google Play. צריך לנסות לשלוח את הבקשה שוב.

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