مراحل نشاط الاشتراك

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

التعامل مع مراحل النشاط للاشتراكات التي يتم تجديدها تلقائيًا

عندما تتغيّر حالة اشتراك المستخدم، يتلقّى خادم الخلفية رسالة SubscriptionNotification.

subs-auto-renew-state
الشكل 1. حالات مراحل النشاط وأحداث الانتقال لعمليات شراء الاشتراكات التي يتم تجديدها تلقائيًا

لتعديل الحالة في الخلفية، استدعِ واجهة برمجة التطبيقات purchases.subscriptionsv2.get مع تضمين رمز الشراء في الإشعار. يوفّر نقطة النهاية هذه أحدث حالة للاشتراك مع توفير رمز مميّز لعملية الشراء، وتُعدّ مصدر المعلومات الموثوق لإدارة الاشتراكات.

يكون الرمز المميز للشراء صالحًا من وقت الاشتراك وحتى 60 يومًا بعد انتهاء الصلاحية. وبعد هذا التاريخ، لن يكون رمز الشراء صالحًا لاستخدامه في استدعاء Google Play Developer API.

عمليات شراء اشتراكات جديدة يتم تجديدها تلقائيًا

عندما يشتري المستخدم اشتراكًا، يتم إرسال رسالة SubscriptionNotification من النوع SUBSCRIPTION_PURCHASED إلى عميل RTDN. سواء تلقّيت هذا الإشعار أو سجّلت عملية شراء جديدة داخل التطبيق من خلال 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 Billing Library.

يتيح لك مزامنة حالة الاشتراك مع الخلفية أن تكون على دراية أكبر بحالات رفض الدفع، كما يمنحك المزيد من السياق أثناء محاولتك الحدّ من حالات التوقف غير الطوعي عن الاشتراك. استمع إلى رسائل 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 المستخدمين الذين يستفيدون من فترة سماح بأنّه تم رفض دفعتهم ويطلب منهم حلّ المشاكل المتعلّقة بطريقة الدفع في متجر Google Play. عندما يدخل المستخدم فترة سماح، عليك أيضًا تشجيعه على حلّ مشكلة طريقة الدفع في حال كان الخطأ غير مقصود. إحدى الطرق المباشرة لتنفيذ ذلك هي استخدام In-App Messaging API. إذا طلبت تنفيذ واجهة برمجة التطبيقات هذه عندما يفتح المستخدم تطبيقك، ستظهر له رسالة من Play في شريط إشعارات مؤقت لإبلاغه بأنّه تم رفض دفعه. تتضمّن هذه الرسالة أيضًا رابطًا لصفحة معيّنة كي يتمكّن المستخدم من حلّ المشكلة في طريقة الدفع على Google Play.

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

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

الوصول إلى الحساب واسترداده خلال فترة السماح

يوضّح الشكل 2 مخططًا زمنيًا لاشتراك يدخل في فترة سماح ثم تتم استعادته عندما يحلّ المستخدم مشكلة طريقة الدفع. بعد انتهاء فترة السماح، يجب أن يفقد المستخدم مزايا الاشتراك ويتم تعليق حسابه.

الشكل 2. المخطط الزمني لاشتراك يدخل في فترة سماح ويتم استرداده قبل انتهائها

من المهم تذكُّر النقاط التالية:

  • خلال فترة السماح، يجب أن يحتفظ المستخدم بإمكانية الوصول إلى مزايا الاشتراك.
  • عند استرداد اشتراك خلال فترة السماح، لن تتم إعادة ضبط تاريخ التجديد.
  • إذا غيّرت فترة السماح، لن يتأثر المستخدمون الذين يستفيدون حاليًا من فترة السماح. سيتم تطبيق فترة السماح الجديدة على عمليات تجديد الاشتراكات التي تدخل فترة السماح بعد إجراء التغيير. على سبيل المثال، إذا غيّرت فترة السماح من 7 أيام إلى 14 يومًا، سيستفيد المستخدمون الذين يدخلون فترة السماح بعد التغيير من فترة السماح الجديدة البالغة 14 يومًا.
  • يظل الاشتراك نشطًا ولن تتلقّى إشعارًا في الوقت الفعلي بشأن رفض الدفع خلال فترة السماح الصامتة إلى أن تنتهي هذه الفترة.

فترة السماح الصامتة

يمكنك ضبط فترة سماح تبلغ 0 يوم، ولكن سيتم الانتظار لمدة يوم واحد على الأقل في Play لضمان توفّر وقت كافٍ لإعادة محاولة الدفع. توفّر فترة السماح غير المعلَنة هذه شبكة أمان لمعالجة الدفعات. وخلال فترة الـ 24 ساعة هذه، يظل الاشتراك في الحالة ACTIVE.

أفضل طريقة لمتابعة التغييرات في حالة الاشتراك هي الاستماع إلى الإشعارات في الوقت الفعلي الخاصة بالمطوّرين (RTDN) والتفاعل معها. استخدِم طريقة purchases.subscriptionsv2.get() في وقت RTDN بدلاً من وقت انتهاء الصلاحية للحصول على حالة اشتراك أكثر دقة.

استنادًا إلى حالة الاشتراك بعد فترة السماح الصامتة التي تبلغ 24 ساعة، من المفترض أن تتلقّى أحد الإشعارات التالية:

  • ‫SUBSCRIPTION_ON_HOLD (في حال التفعيل)
  • ‫SUBSCRIPTION_CANCELED (في حال الإلغاء)
  • ‫SUBSCRIPTION_EXPIRED (في حال انتهاء الصلاحية)
  • ‫SUBSCRIPTION_RENEWED (في حال تم تجديد الاشتراك بنجاح)

يمكنك أيضًا استدعاء طريقة subscriptionV2.get() في أي وقت بعد فترة السماح الصامتة التي تبلغ 24 ساعة للحصول على آخر حالة للاشتراك.

فترة تعليق الاشتراك

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

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

تُعلمك الإشعارات في الوقت الفعلي عند دخول المستخدم فترة تعليق الاشتراك، ما يتيح لك إبلاغه في أقرب وقت ممكن بسبب تعليق إمكانية وصوله إلى الاشتراك. يمكن إجراء ذلك بسهولة من خلال استخدام In-App Messaging API. سيؤدي استدعاء واجهة برمجة التطبيقات هذه عندما يفتح المستخدم تطبيقك إلى عرض رسالة في شريط إعلام مؤقت لإبلاغه بأنّه تم رفض دفعه. تتضمّن هذه الرسالة أيضًا رابطًا لصفحة في التطبيق يتيح للمستخدم حلّ المشكلة في طريقة الدفع على Google Play.

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

لا تعرض طريقة queryPurchasesAsync() الاشتراك أثناء تعليق الحساب، لذا إذا كان تطبيقك يعتمد على هذه الطريقة لعرض عمليات الشراء الحالية، عليك إتاحة تعليق الحساب تلقائيًا.

باستخدام الإشعارات في الوقت الفعلي الخاصة بالمطوّرين، ستتلقّى رسالة SubscriptionNotification من النوع SUBSCRIPTION_ON_HOLD عندما ينتقل الاشتراك إلى حالة تعليق الحساب. استدعِ طريقة 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 Billing Library الاشتراك مرة أخرى من خلال الطريقة 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,
      ...
    }
  ],
}

إذا لم يحلّ المستخدم مشكلة طريقة الدفع قبل انتهاء فترة تعليق الحساب، ستتلقّى بدلاً من ذلك إشعارًا في الوقت الفعلي بعدم التسليم من النوع SUBSCRIPTION_CANCELED. للحصول على تعليمات حول كيفية التعامل مع عملية إلغاء، يُرجى الاطّلاع على عمليات الإلغاء. عند البحث عن اشتراك تم إلغاؤه بهذه الطريقة، يتم ضبط الحقل expiryTime الذي يتم عرضه على طابع زمني سابق:

{
  "kind": "androidpublisher#subscriptionPurchaseV2",
  ...
  "subscriptionState": "SUBSCRIPTION_STATE_CANCELED",
  ...
  "lineItems": [
    {
      "productId": "sub_variant_plan01",
      "expiryTime": timestamp_in_past,
      ...
    }
  ],
}

بعد تلقّي إشعار الإلغاء مباشرةً أثناء تعليق الاشتراك، ستتلقّى أيضًا إشعارًا في الوقت الفعلي من النوع SUBSCRIPTION_EXPIRED لأنّ المستخدم لم يعُد يملك حق الاستخدام المدفوع وتم إلغاء الاشتراك. يمكنك التعامل مع انتهاء الصلاحية هذا بالطريقة المعتادة.

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

الوصول إلى الحساب المعلق واسترداده

يعرض الشكل 3 مخططًا زمنيًا لاشتراك تم تعليقه ثم استعادته بعد أن حلّ المستخدم مشكلة طريقة الدفع.

الشكل 3. المخطط الزمني للاشتراك الذي يتم تعليقه مؤقتًا ثم استئنافه قبل انتهائه

على غرار المثال السابق، يعرض الشكل 4 مخططًا زمنيًا لاشتراك يدخل أولاً في فترة سماح قبل تعليق الحساب، ثم يتم استرداده أثناء تعليقه.

الشكل 4. المخطط الزمني للاشتراك الذي يدخل في فترة سماح، ثم يتم تعليقه، ثم يتم استرداده قبل انتهاء فترة تعليق الاشتراك

من المهم تذكُّر النقاط التالية:

  • قبل أن يتم تعليق الاشتراك، يجري Google Play محاولات إضافية لتحصيل الرسوم من طريقة الدفع لمدة تصل إلى 48 ساعة. ويحتفظ المستخدم بمزايا الاشتراك خلال هذه الفترة. بعد انقضاء فترة إعادة المحاولة هذه، يتم تعليق الاشتراك، ويجب أن يفقد المستخدم إمكانية الوصول إلى مزايا الاشتراك.
  • يدخل الاشتراك في حالة تعليق الحساب مباشرةً عند استئناف الاشتراك من حالة الإيقاف المؤقت مع تعذُّر استخدام طريقة الدفع.
  • عند استرداد اشتراك بعد تعليقه، تتم إعادة ضبط تاريخ التجديد.

فترات انتهاء الصلاحية

بعد انتهاء صلاحية الاشتراك، يجب أن يفقد المستخدم إمكانية الوصول إليه. في هذه الحالة، يتم إرسال رسالة SubscriptionNotification من النوع SUBSCRIPTION_EXPIRED. عند تلقّي هذا الإشعار، أرسِل طلب بحث إلى 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_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(). ننصحك بعرض رسالة في تطبيقك لإبلاغ المستخدم بأنّه تم إلغاء اشتراكه وتحديد تاريخ انتهاء صلاحيته.

عمليات الإبطال

يمكن إلغاء الاشتراك لعدة أسباب، بما في ذلك إلغاء الخلفية للاشتراك باستخدام purchases.subscriptionsv2.revoke أو ردّ الأموال المدفوعة مقابل عملية الشراء. في هذه الحالة، عليك إبطال إذن استخدام المستخدم على الفور. يتم إرسال رسالة SubscriptionNotification من النوع SUBSCRIPTION_REVOKED عند حدوث ذلك. عند تلقّي هذا الإشعار، سيتم ضبط الحقل subscriptionState على القيمة SUBSCRIPTION_STATE_EXPIRED في مصدر الاشتراك الذي يتم عرضه من خلال Google Play Developer API.

يبدو مصدر الاشتراك لعملية شراء تم إبطالها مشابهًا للمثال التالي:

{
  "kind": "androidpublisher#subscriptionPurchaseV2",
  ...
  "subscriptionState": "SUBSCRIPTION_STATE_EXPIRED",
  ...
  "lineItems": [
    {
      "productId": "sub_variant_plan01",
      "expiryTime": expiration_time,
      ...
    }
  ]
}

الاشتراكات المؤجّلة

هناك عدة أسباب قد تدفعك إلى تمديد إذن استخدام المستخدم. على سبيل المثال، قد تريد تقديم وصول مجاني للمستخدمين كعرض ترويجي خاص، مثل منح أسبوع مجاني عند شراء فيلم أو تقديم وصول مجاني للعملاء كبادرة حسن نية.

يمكنك استخدام واجهة برمجة التطبيقات purchases.subscriptionsv2.defer لتأجيل تاريخ الفوترة للاشتراكات (بما في ذلك الاشتراكات التي تتضمّن إضافات). عند تأجيل اشتراك يتضمّن ميزات إضافية، يتم تأجيل جميع العناصر في الاشتراك لمدة مماثلة.

عند تأجيل الاشتراك، يتم إرسال رسالة SubscriptionNotification من النوع SUBSCRIPTION_DEFERRED. خلال فترة التأجيل، يكون المستخدم مشتركًا في المحتوى الخاص بك مع إمكانية الوصول الكامل إليه، ولكن لا يتم تحصيل رسوم منه. سيتم تعديل تاريخ تجديد الاشتراك ليوافق التاريخ الجديد.

بالنسبة إلى خطط الدفع المُسبَق، يمكنك استخدام واجهة برمجة التطبيقات الخاصة بتأجيل الفوترة لتأجيل وقت انتهاء الصلاحية.

يبدو مصدر الاشتراك المؤجّل مشابهًا للمثال التالي:

{
  "kind": "androidpublisher#subscriptionPurchaseV2",
  ...
  "subscriptionState": "SUBSCRIPTION_STATE_ACTIVE",
  ...
  "lineItems": [
    {
      "productId": "sub_variant_plan01",
      "expiryTime": timestamp_in_future,
      ...
    }
  ],
}

الاشتراكات المتوقفة مؤقتًا

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

تكرار الاشتراك أسبوعيًا شهريًا ثلاثة أشهر ستة أشهر سنويًا
مدد الإيقاف المؤقت المتاحة* أسبوع واحد
أسبوعان
3 أسابيع
4 أسابيع		 شهر واحد
شهرَين
3 أشهر		 شهر واحد
شهرَين
3 أشهر		 شهر واحد
شهرَين
3 أشهر		 شهر واحد
شهرَين
3 أشهر
*قد تتغيّر في أي وقت.

لا يتم إيقاف الاشتراك مؤقتًا إلا بعد انتهاء المدة الحالية للفوترة. أثناء إيقاف الاشتراك مؤقتًا، لا يمكن للمستخدم الوصول إلى الاشتراك، ولا يدفع سعر التجديد. عند انتهاء مدة الإيقاف المؤقت، يتم استئناف الاشتراك وتحاول Google تجديده. وفي حال تم تفعيل استئناف الاشتراك، سيصبح نشطًا مرة أخرى. إذا تعذّر استئناف الاشتراك بسبب مشكلة في الدفع، سيصبح حساب المستخدم في حالة تعليق كما هو موضّح في الشكلين 5 و6:

الشكل 5. يعلّق المستخدم اشتراكه مؤقتًا ثم يستأنفه.
الشكل 6. يعلّق المستخدم اشتراكه ثم يدخل في فترة تعليق الحساب.

يمكن للمستخدم أيضًا اختيار استئناف الاشتراك يدويًا في أي وقت خلال فترة الإيقاف المؤقت، كما هو موضّح في الشكل 6. عندما يستأنف المستخدم الاشتراك يدويًا، يتغيّر تاريخ الفوترة إلى تاريخ الاستئناف اليدوي.

عند إيقاف اشتراك المستخدم مؤقتًا، لا تعرض "مكتبة الفوترة في Play" الاشتراك من خلال طريقة queryPurchasesAsync() ما لم يتم ضبط المَعلمة includeSuspendedSubscriptions على "صحيح" في QueryPurchasesParams. في حال استئناف الاشتراك، ستعرض الطريقة queryPurchasesAsync() الاشتراك مرة أخرى.

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

يتم إرسال رسالة SubscriptionNotification من النوع SUBSCRIPTION_PAUSE_SCHEDULE_CHANGED عندما يبدأ المستخدم في إيقاف اشتراكه مؤقتًا. في هذا الوقت، من المفترض أن يظل بإمكان المستخدم الوصول إلى اشتراكه حتى تاريخ التجديد التالي، وأن يحتوي مصدر الاشتراك على autoRenewEnabled = true. قيمة الحقل subscriptionState هي SUBSCRIPTION_STATE_ACTIVE في هذه المرحلة.

يتم إرسال رسالة SubscriptionNotification من النوع SUBSCRIPTION_PAUSED عند بدء فترة التوقف المؤقت. في هذه الحالة، من المفترض أن يفقد المستخدم إمكانية الوصول إلى اشتراكه، وأن يحتوي مورد الاشتراك على autoRenewEnabled = true، وأن يتم ضبط الحقل subscriptionState على SUBSCRIPTION_STATE_PAUSED. يمكنك معرفة الموعد المتوقّع لتجديد الاشتراك مرة أخرى من خلال التحقّق من العنصر PausedStateContext.

يتم إرسال رسالة SubscriptionNotification من النوع SUBSCRIPTION_RECOVERED في حال استئناف الاشتراك تلقائيًا في نهاية فترة الإيقاف المؤقت أو إذا اختار المستخدم استئناف الاشتراك يدويًا.

يتم إرسال رسالة SubscriptionNotification من النوع SUBSCRIPTION_ON_HOLD في حال تعذّر الدفع عند محاولة استئناف الاشتراك بعد إيقافه مؤقتًا.

يجب التعامل مع كلتا الحالتين كما هو موضّح في مقالة تعليق الحساب.

إعادة الاشتراك

بالنسبة إلى الخطط الأساسية للاشتراكات التي تتجدّد تلقائيًا، قد يعرض "متجر Google Play" زر إعادة الاشتراك. يتيح هذا الزر للمستخدمين استعادة إمكانية الوصول إلى اشتراك. قد لا يظهر لعدة أسباب، مثلاً عندما انتهت صلاحية الاشتراك منذ فترة طويلة.

الشكل 7. قسم الحساب > الاشتراكات في تطبيق "متجر Google Play" يعرض اشتراكًا تم إلغاؤه مع زر إعادة الاشتراك.

على الرغم من أنّ الزر يحمل دائمًا التصنيف إعادة الاشتراك، تعتمد وظائفه على حالة الاشتراك.

عندما يتم إلغاء الاشتراك ولكن لم تنتهِ صلاحيته بعد، يظل المستخدم مشتركًا ويستفيد من مزايا الاشتراك. إذا نقر المستخدم على "إعادة الاشتراك"، سيتم التراجع عن الإلغاء، وسيستمر تجديد الاشتراك. يُعرف هذا الإجراء باسم استعادة في مستندات المطوّرين وواجهات برمجة التطبيقات على Play.

بعد انتهاء صلاحية اشتراك يتجدّد تلقائيًا، يمكنك السماح للمستخدمين بشراء الخطة الأساسية نفسها للاشتراك. يُعرف هذا الإجراء باسم إعادة الاشتراك في مستندات المطوّرين وواجهات برمجة التطبيقات على Play. يمكنك ضبط هذا الخيار لكل خطة أساسية في Play Console أو باستخدام واجهة برمجة التطبيقات.

الاستعادة قبل انتهاء الصلاحية

إذا كان تطبيقك يعتمد فقط على الطريقة queryPurchasesAsync() لتحديد ما إذا كان المستخدم مؤهلاً للاشتراك، يجب أن يتعامل تطبيقك تلقائيًا مع عمليات الاستعادة لأنّ الطريقة queryPurchasesAsync() تستمر في عرض عمليات الشراء الملغاة قبل تواريخ انتهاء صلاحيتها. يستمر تجديد الاشتراك الذي تم استرداده كما لو لم يتم إلغاؤه.

إذا كان تطبيقك يزامن حالة الاشتراك مع خادم الخلفية، عليك الاستماع إلى رسالة SubscriptionNotification من النوع SUBSCRIPTION_RESTARTED. بعد تلقّي إشعار RTDN هذا، يمكن لتطبيقك الردّ على الإشعار وتسجيل أنّه تم ضبط الاشتراك على التجديد، والتوقّف عن عرض رسائل الاستعادة في تطبيقك. يبدو مورد الاشتراك مشابهًا للمثال التالي:

{
  "kind": "androidpublisher#subscriptionPurchaseV2",
  ...
  "subscriptionState": "SUBSCRIPTION_STATE_ACTIVE",
  ...
  "lineItems": [
    {
      "productId": "sub_variant_plan01",
      "expiryTime": next_renewal_date
      ...
    }
  ],
}

لا تؤدي استعادة اشتراك إلى إنشاء طلب جديد. إذا ظهر لك طلب بقيمة 0.00 دولار أمريكي للاشتراك الذي ألغاه المستخدم سابقًا، من المحتمل أن يكون المستخدم قد اشترك مجددًا من تطبيقك قبل انتهاء صلاحية الاشتراك. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة الترقية إلى خطة أعلى أو أقلّ كلفة وإعادة الاشتراك.

إعادة الاشتراك بعد انتهاء الصلاحية

إذا تم إعداد خطة أساسية تتجدّد تلقائيًا باستخدام Google Play Console أو واجهة برمجة التطبيقات للسماح بإعادة الاشتراك، يمكن للمستخدمين إعادة شراء اشتراك منتهي الصلاحية في "متجر Google Play".

هذه عمليات شراء جديدة. يصدر Google Play رمزًا مميزًا جديدًا لعملية الشراء، ويتلقّى الخلفية RTDN من النوع SUBSCRIPTION_PURCHASED. لا تتضمّن حالة الشراء لهذا النوع من عمليات الشراء خارج التطبيق linkedPurchaseToken مرتبطًا بعملية الشراء الأصلية في هذه الحالة، لأنّ الاشتراك الأصلي انتهت صلاحيته تمامًا.

لضمان ربط المستخدمين بشكل صحيح بالاشتراكات التي تمّت إعادة شرائها ومنع عمليات ردّ الأموال تلقائيًا مقابل عمليات الشراء التي لم يتمّ الإقرار بها، عليك الإقرار بعملية إعادة الشراء على خادم الخلفية باتّباع الخطوات التالية:

  1. اتّصِل بالرقم purchases.subscriptionsv2.get باستخدام الرمز المميّز الجديد لعملية الشراء من الإشعار في الوقت الفعلي الخاص بالمطوّرين. تتضمّن الاستجابة لهذا النوع من عمليات الشراء خارج التطبيق الحقل outOfAppPurchaseContext، وهو مخصّص حصريًا لعمليات شراء إعادة الاشتراك التي لم يتم إعلامنا باستلامها. يوفّر هذا الحقل ما يلي:

    • ‫expiredExternalAccountIdentifiers: عنصر ExternalAccountIdentifiers يحتوي على الحقلَين obfuscatedAccountId وobfuscatedProfileId اللذين تم ضبطهما للاشتراك السابق المنتهي الصلاحية، إذا تم ضبطهما.
    • ‫expiredPurchaseToken: الرمز المميّز لعملية شراء آخر اشتراك انتهت صلاحيته.

    استخدِم أحد هذين المعرّفَين للبحث عن عملية الشراء الجديدة وربطها بحساب المستخدم الصحيح في الخلفية.

  2. يُرجى الاتصال بالرقم purchases.subscriptions.acknowledge للإقرار بعملية الشراء.

    • يمكنك اختياريًا إرسال obfuscatedAccountId وobfuscatedProfileId الخاصين بالمستخدم إذا كنت قد أعددتهما باستخدام setObfuscatedAccountId وsetObfuscatedProfileId أثناء مسار الفوترة داخل التطبيق.

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

الترقية والرجوع إلى إصدار سابق وإعادة الاشتراك

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

بالإضافة إلى ذلك، يحتوي مصدر الاشتراك الذي يتم عرضه من خلال Google Play Developer API على الحقل linkedPurchaseToken الذي يشير إلى عملية الشراء القديمة التي تمت ترقية الاشتراك أو خفضه أو إعادة الاشتراك من خلالها. يمكنك استخدام الرمز المميز للشراء في هذا الحقل للبحث عن الاشتراك القديم وتحديد حساب المستخدم الحالي حتى تتمكّن من ربط عملية الشراء الجديدة بالحساب نفسه.

عندما يشترك المستخدم مرة أخرى من تطبيقك في الخطة الأساسية نفسها قبل انتهاء صلاحية اشتراكه، يُصدر Google Play طلبًا بقيمة 0.00 دولار أمريكي لعملية الشراء الجديدة. لا يتم تحصيل أي رسوم من المستخدم عند الاشتراك، وذلك لأنّه قد سدّد بالفعل تكلفة مدة الفوترة الحالية. تُستأنف الفوترة العادية في تاريخ التجديد الأصلي. يظهر الطلب الذي تبلغ قيمته 0.00 دولار أمريكي في قسم إدارة الطلبات في Play Console وفي تقاريرك المالية. ولا يعني ذلك أنّ المستخدم حصل على فترة تجريبية مجانية أو خصم ترويجي.

قبل أن توفّر للمستخدم خيارات الترقية أو الرجوع إلى إصدار أقدم أو إعادة الاشتراك في تطبيقك، عليك الإقرار بالاشتراك الحالي. يتم حظر أي تغيير في الخطة أو إعادة الاشتراك إذا كان الاشتراك الحالي لا يزال في انتظار التأكيد.

إذا نجح المستخدم في شراء ترقية أو الرجوع إلى إصدار أقدم أو إعادة الاشتراك، يكون هذا عملية شراء جديدة يجب إقرارها. الطريقة المقترَحة لإجراء ذلك هي استخدام 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
      }
    }
  ],
}

تغييرات السعر

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

عند إضافة تغيير في السعر وعند إجراء أي تعديلات على حالة تغيير السعر، ستتلقّى إشعارًا في الوقت الفعلي من النوع SUBSCRIPTION_PRICE_CHANGE_UPDATED. يمكنك إرسال طلب إلى نقطة النهاية purchases.subscriptionsv2.get للحصول على مورد اشتراك يتضمّن تفاصيل تغيير السعر لكل منتج في الاشتراك.

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

التعامل مع تأكيد المستخدم لتغيير السعر الذي يتطلّب موافقة

عندما يوافق المستخدم على زيادة سعر الاشتراك، ستتلقّى رسالة SubscriptionNotification من النوع SUBSCRIPTION_PRICE_CHANGE_UPDATED.

التعامل مع عمليات التجديد بعد تطبيق تغيير السعر

عند انخفاض السعر أو عند تجديد اشتراكك بعد زيادة السعر، ستتلقّى رسالة SubscriptionNotification من النوع SUBSCRIPTION_RENEWED. تعامَل مع هذا الإشعار كأي تجديد آخر.

التعامل مع الحالات التي لا يتم فيها قبول زيادة في السعر تتطلّب موافقة

إذا لم يوافق المستخدم على الزيادة الاختيارية في السعر قبل أن يحتاج إلى تجديد الاشتراك بالسعر الجديد، سيتم إلغاء اشتراكه تلقائيًا وستتلقّى رسالة SubscriptionNotification من النوع SUBSCRIPTION_CANCELED. تعامَل مع هذا الحدث كما هو موضّح في قسم عمليات الإلغاء.

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

بموجب اللوائح التنظيمية الجديدة في كوريا الجنوبية، يجب أن يوافق المستخدمون الذين لديهم اشتراكات في هذه المنطقة على أي زيادات في الأسعار ستحدث بعد انتهاء الفترة التجريبية المجانية أو الفترة التمهيدية.

لمساعدتك في الالتزام باللائحة التنظيمية، سيُرسل Play إشعارًا إلى المستخدمين في منطقة كوريا الجنوبية بشأن متطلبات الموافقة، وسيخزّن أيضًا ردود المستخدمين على طلب الموافقة. يتم إلغاء الاشتراكات تلقائيًا للمستخدمين الذين لا يوافقون على السعر الجديد قبل تطبيقه. بالإضافة إلى الإشعارات التي يتم إرسالها من Play، يمكنك أيضًا إرسال إشعارات مخصّصة بشأن زيادة الأسعار إلى المستخدمين، ويمكنك تقديم رابط إلى صفحة إدارة معيّنة في إشعاراتك.

عندما تبدأ فترة الموافقة أو يقدّم المستخدم موافقته، ستتلقّى رسالة SubscriptionNotification من النوع SUBSCRIPTION_PRICE_STEP_UP_CONSENT_UPDATED.

الفرق بين زيادة السعر وتغيير السعر

يشير price step-up إلى زيادة في سعر الاشتراك بسبب الانتقال من مرحلة عرض إلى أخرى. على سبيل المثال، الانتقال من فترة تجريبية مجانية إلى سعر عادي. يمكنك استخدام الحقل offerPhase في مورد الاشتراك لتحديد المرحلة الحالية من الاشتراك.

ومع ذلك، يشير price change إلى تعديلات الأسعار التي تبدأها أنت (المطوّر) لسعر الخطة الأساسية للاشتراك. على سبيل المثال، زيادة في السعر تتطلّب موافقة أو زيادة في السعر لا تتطلّب موافقة.

التعامل مع مراحل النشاط لخطط الدفع المُسبَق

كما هو الحال مع الاشتراكات التي يتم تجديدها تلقائيًا، يجب الإقرار بخطط الدفع المُسبق بعد كل عملية شراء جديدة. في حالة خطط الدفع المُسبق، يجب إكمال عملية الشراء الأولية وأي عمليات إضافة رصيد، لأنّ المستخدم عليه اتّباع خطوات مسار الشراء في كل مرة.

نظرًا إلى إمكانية أن تكون مدة خطط الدفع المسبق قصيرة، من المهم إقرار عملية الشراء في أقرب وقت ممكن. يجب الموافقة على خطط الدفع المُسبَق التي تبلغ مدتها أسبوعًا واحدًا أو أكثر في غضون 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 للخطط المدفوعة مسبقًا

تمت إضافة حقول جديدة لتوفير خطط الدفع المُسبَق التي يمدّدها المستخدم بدلاً من تجديدها تلقائيًا. تنطبق جميع الحقول على خطط الدفع المُسبَق كما تنطبق على الاشتراكات التي يتم تجديدها تلقائيًا، باستثناء ما يلي:

  • [حقل جديد] lineItems[0].prepaid_plan.allowExtendAfterTime: يشير إلى الوقت الذي سيُسمح فيه للمستخدم بشراء رصيد إضافي آخر لتمديد خطة الدفع المُسبَق، إذ يُسمح للمستخدم بالحصول على رصيد إضافي واحد فقط لم يتم استخدامه في كل مرة.
  • [حقل جديد] SubscriptionState: يحدّد حالة عنصر الاشتراك. بالنسبة إلى خطط الدفع المُسبق، تكون هذه القيمة دائمًا ACTIVE أو PENDING أو CANCELED.
  • lineItems[0].expiryTime: يتوفّر هذا الحقل دائمًا للخطط المدفوعة مسبقًا.
  • paused_state_context: لا يظهر هذا الحقل أبدًا لأنّه لا يمكن إيقاف الخطط المدفوعة مسبقًا مؤقتًا.
  • lineItems[0].auto_renewing_plan: غير متوفّر لخطط الدفع المُسبَق.
  • canceled_state_context: لا يتوفّر هذا الحقل في الخطط المدفوعة مسبقًا، لأنّه ينطبق فقط على المستخدمين الذين يلغون الاشتراك بشكل نشط.
  • lineItems[0].productId: يحلّ هذا الحقل محل subscriptionId من الإصدارات السابقة.