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 في المستقبل في حال عدم إدخالها، لن تكون BasePlan متاحة تلقائيًا في أي مواقع جغرافية جديدة قد يتيحها 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.

إذا لم يتم تحديدها، تكون القيمة التلقائية هي P30D.

يجب أن يتراوح إجمالي 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.

إذا لم يتم تحديدها، تكون القيمة التلقائية هي P30D.

يجب أن يتراوح إجمالي 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". إذا لم يتم تحديد ذلك، سيتم ضبط القيمة التلقائية على 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 حرفًا. نص عادي

الطُرق

archive
(deprecated)

 تم إيقاف الميزة: لا تتوفّر ميزة أرشفة الاشتراكات.

batchGet

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

batchUpdate

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

create

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

delete

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

get

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

list

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

patch

 تعدّل هذه الطريقة اشتراكًا حاليًا.