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) وشرطات سفلية (_) ونقاط (.)، وأن يبدأ بحرف إنجليزي صغير أو رقم، وأن يتراوح طوله بين حرف واحد و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 في المستقبل في حال عدم إدخالها، لن تكون "الخطة الأساسية" متاحة تلقائيًا في أي مواقع جغرافية جديدة قد يتيحها Play في المستقبل.
حقل الربط base_plan_type نوع هذه الخطة الأساسية. يجب ضبط قيمة واحدة بالضبط. لا يمكن تغيير نوع الخطة الأساسية بعد إنشائها. يمكن أن يكون التعليق base_plan_type إحدى القيم التالية فقط:
autoRenewingBasePlanType

object (AutoRenewingBasePlanType)

تحديد موعد تجديد الخطة الأساسية تلقائيًا على فترات منتظمة
prepaidBasePlanType

object (PrepaidBasePlanType)

تُستخدَم لتحديد الوقت الذي لا يتم فيه تجديد الخطة الأساسية تلقائيًا في نهاية مدة الفوترة.
installmentsBasePlanType

object (InstallmentsBasePlanType)

يتم ضبطها لخطط التقسيط الأساسية التي يلتزم فيها المستخدم بتسديد عدد محدّد من الدفعات.

ولاية

الحالة الحالية للخطة الأساسية

عمليات التعداد
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 أو مدة فوترة الخطة الأساسية.

في حال عدم تحديدها، سيتم استخدام قيمة تلقائية استنادًا إلى مدة الفوترة.

يجب أن يتراوح إجمالي عدد أيام gracePeriodDuration وaccountHoldDuration بين P30D وP60D يومًا.
accountHoldDuration

string

اختياريّ. تمثّل هذه السمة فترة تعليق الاشتراك المخصّصة، ويتم تحديدها بتنسيق ISO 8601. يجب أن تكون القيم المقبولة بالأيام وأن تتراوح بين P0D وP60D.

يمثّل الحقل الفارغ فترة تعليق الاشتراك المقترَحة، ويتم احتسابها على النحو التالي: 60 يومًا ناقص فترة السماح.

يجب أن يتراوح إجمالي عدد أيام gracePeriodDuration وaccountHoldDuration بين P30D وP60D يومًا.
resubscribeState

enum (ResubscribeState)

تحدّد هذه السمة ما إذا كان بإمكان المستخدمين إعادة الاشتراك في هذه الخطة الأساسية في مساحات عرض Google Play. يتم ضبط القيمة تلقائيًا على RESUBSCRIBE_STATE_ACTIVE في حال عدم تحديدها.
prorationMode

enum (SubscriptionProrationMode)

يحدّد وضع التقسيم النسبي للخطة الأساسية ما يحدث عندما ينتقل المستخدم إلى هذه الخطة من خطة أساسية أخرى. إذا لم يتم تحديدها، تكون القيمة التلقائية هي CHARGE_ON_NEXT_BILLING_DATE.
legacyCompatible

boolean

تُستخدَم لتحديد ما إذا كانت الخطة الأساسية المتجدّدة متوافقة مع الأنظمة القديمة.

يتم عرض الخطة الأساسية المتوافقة مع الإصدارات القديمة من خلال الإجراء querySkuDetailsAsync()‎ المتوقف نهائيًا والخاص بواجهة برمجة التطبيقات Google Play Billing Library.

يمكن وضع علامة على خطة أساسية واحدة متجدّدة على أنّها متوافقة مع الإصدارات القديمة لاشتراك معيّن.
legacyCompatibleSubscriptionOfferId

string

معرّف العرض الترويجي للاشتراك المتوافق مع الإصدار القديم

يتم عرض عرض الاشتراك المتوافق مع الأنظمة القديمة من خلال الإجراء querySkuDetailsAsync()‎ المتوقف نهائيًا والخاص بواجهة برمجة التطبيقات Google Play Billing Library.

يمكن وضع علامة على عرض اشتراك واحد فقط على أنّه متوافق مع الإصدارات القديمة لخطة أساسية محدّدة يتم تجديدها.

لعدم توفّر عرض اشتراك متوافق مع الإصدارات القديمة، اضبط هذا الحقل على سلسلة فارغة.

ResubscribeState

حالة إعادة الاشتراك في الخطة الأساسية

عمليات التعداد
RESUBSCRIBE_STATE_UNSPECIFIED حالة غير محدَّدة
RESUBSCRIBE_STATE_ACTIVE ميزة "إعادة الاشتراك" مفعَّلة.
RESUBSCRIBE_STATE_INACTIVE خيار إعادة الاشتراك غير مفعَّل.

SubscriptionProrationMode

وضع التسعير النسبي المستخدَم لتجديد الخطط الأساسية

عمليات التعداد
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

تمديد مدة الخطة الأساسية

عمليات التعداد
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)

الحقل مطلوب. غير قابل للتغيير نوع تجديد الخطة الأساسية بالتقسيط يحدّد هذا الإعداد السلوك في نهاية مدة الاشتراك الأولية. لا يمكن تغيير نوع التجديد بعد إنشاء الخطة الأساسية.
gracePeriodDuration

string

تمثّل هذه السمة فترة السماح للاشتراك، ويتم تحديدها بتنسيق ISO 8601. يجب أن تكون القيم المقبولة بالأيام وأن تتراوح بين P0D وأقل من 30D ومدة فوترة الخطة الأساسية.

في حال عدم تحديدها، سيتم استخدام قيمة تلقائية استنادًا إلى مدة الفوترة.

يجب أن يتراوح إجمالي عدد أيام gracePeriodDuration وaccountHoldDuration بين P30D وP60D يومًا.
accountHoldDuration

string

اختياريّ. تمثّل هذه السمة فترة تعليق الاشتراك المخصّصة، ويتم تحديدها بتنسيق ISO 8601. يجب أن تكون القيم المقبولة بالأيام وأن تتراوح بين P0D وP60D.

يمثّل الحقل الفارغ فترة تعليق الاشتراك المقترَحة، ويتم احتسابها على النحو التالي: 60 يومًا ناقص فترة السماح.

يجب أن يتراوح إجمالي عدد أيام gracePeriodDuration وaccountHoldDuration بين P30D وP60D يومًا.
resubscribeState

enum (ResubscribeState)

تحدّد هذه السمة ما إذا كان بإمكان المستخدمين إعادة الاشتراك في هذه الخطة الأساسية في مساحات عرض Google Play. يتم ضبط القيمة تلقائيًا على RESUBSCRIBE_STATE_ACTIVE في حال عدم تحديدها.
prorationMode

enum (SubscriptionProrationMode)

يحدّد وضع التقسيم النسبي للخطة الأساسية ما يحدث عندما ينتقل المستخدم إلى هذه الخطة من خطة أساسية أخرى. إذا لم يتم تحديدها، تكون القيمة التلقائية هي CHARGE_ON_NEXT_BILLING_DATE.

RenewalType

نوع تجديد الخطة الأساسية بالتقسيط يحدّد هذا الإعداد السلوك في نهاية مدة الاشتراك الأولية. لا يمكن تغيير نوع التجديد بعد إنشاء الخطة الأساسية.

عمليات التعداد
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". إذا لم يتم تحديد ذلك، سيتم ضبط القيمة التلقائية على "خطأ".
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. إذا لم يتم تحديد ذلك، سيتم ضبط القيمة التلقائية على "خطأ".

SubscriptionListing

البيانات الوصفية للاشتراك التي تظهر للمستهلكين

تمثيل JSON 
{
  "languageCode": string,
  "title": string,
  "benefits": [
    string
  ],
  "description": string
}
الحقول
languageCode

string

الحقل مطلوب. تمثّل هذه السمة لغة هذه البطاقة، كما هو محدّد في معيار BCP-47، مثلاً "en-US".
title

string

الحقل مطلوب. عنوان هذا الاشتراك بلغة هذه البطاقة. نص عادي
benefits[]

string

قائمة بالمزايا التي تظهر للمستخدم على منصات مثل "متجر Play" وفي عمليات استعادة البيانات بلغة بطاقة البيانات هذه نص عادي قائمة مرتبة تتضمّن أربع مزايا على الأكثر
description

string

تمثّل هذه السمة وصف الاشتراك بهذه اللغة. الحد الأقصى للطول هو 200 حرف. نص عادي

الطُرق

archive
(deprecated)

 تم إيقاف هذه الميزة نهائيًا: لا تتوفّر ميزة أرشفة الاشتراكات.

batchGet

 قراءة اشتراك واحد أو أكثر

batchUpdate

 تعدّل هذه الطريقة مجموعة من الاشتراكات.

create

 تنشئ هذه الطريقة اشتراكًا جديدًا.

delete

 تحذف هذه الطريقة اشتراكًا.

get

 تقرأ هذه السمة اشتراكًا واحدًا.

list

 تعرض هذه الطريقة جميع الاشتراكات ضمن تطبيق معيّن.

patch

 تعديل اشتراك حالي

رموز الخطأ

تعرض عمليات هذا المرجع رموز خطأ HTTP التالية:

رمز الخطأ السبب الوصف الدقة