عقد الاشتراك في تطبيق الجوال

عقد الاشتراك في تطبيق الجوال

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

رمز الخطأ الثابت

errorCode = 1001
code      = "SubscriptionExpired"

تستخدم استجابات الجوال المغلّف القياسي:

اكتشف الانتهاء عبر الرمز لا عبر النص

يجب أن يعتمد التطبيق على errorCode == 1001، أو ما يعادله code == "SubscriptionExpired".

ويجب ألّا يستدل التطبيق على الانتهاء من:

• نص errorMessage الإنجليزي
• نص errorMessage العربي
• مطابقة جزء من أي منهما
• رمز حالة HTTP وحده
• وجهة إعادة التوجيه

فالنصوص مترجَمة وقابلة لإعادة الصياغة في أي وقت، أما الرمز فهو العقد الثابت.

بخصوص السلوك السابق

كان انتهاء الاشتراك يصل سابقًا بالرمز errorCode 17 في عمليات القراءة وبالرمز errorCode 31 في الإرسال. وهذا السلوك مُلغى. فالانتهاء يستخدم الآن الرمز 1001 دائمًا.

ولم يكن الرمزان 17 و31 يخصّان الاشتراك أصلًا، بل هما رمزان عامّان ما زالا مستخدَمَين لمعانيهما المستقلة، مثل عدم توفر ملف أو سؤال، أو استبيان غير مُسنَد إلى حسابك، أو عملية فاشلة. فاستمر في التعامل معهما كما تفعل اليوم، واكتفِ بالتوقف عن اعتبارهما دليلًا على انتهاء الاشتراك.

العمليات التي قد تُرجع SubscriptionExpired

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

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

سلوك تسجيل الدخول والتوكن

أثناء سريان الاشتراك

يعمل تسجيل الدخول بشكل طبيعي ويُصدر توكن JWT.

بعد انتهاء الاشتراك

ما زال تسجيل الدخول يعمل وما زال يُصدر توكن JWT، لأن المصادقة والاستحقاق قراران منفصلان.

فلا تعتبر نجاح تسجيل الدخول دليلًا على أن العمليات ستنجح، إذ قد يُرجع الطلب المحمي التالي مباشرةً الرمز 1001.

توكن صدر قبل الانتهاء

التوكن الأقدم الذي ما زال صالحًا لا يتجاوز الفحص. فحالة الاشتراك تُقرأ من قاعدة البيانات في كل طلب محمي، ولذلك لا أهمية لعمر التوكن.

توكن جديد صدر أثناء الانتهاء

يُرفض أيضًا في العمليات المحمية. فإعادة تسجيل الدخول ليست حلًّا بديلًا، والتطبيق الذي يستجيب للرمز 1001 بإعادة المصادقة سيتلقى 1001 مرة أخرى — فابنِ حالة «مطلوب التجديد» بدلًا من حلقة إعادة تسجيل دخول.

بعد التجديد

يعود التوكن نفسه الصادر قبل الانتهاء إلى العمل فورًا. ولا يلزم أيٌّ مما يلي لمجرد أن الاشتراك انتهى ثم جُدِّد:

• إعادة تثبيت التطبيق أو إعادة تشغيله
• تسجيل الخروج ثم الدخول من جديد
• تحديث التوكن أو استبداله
• انتظار انتهاء أي تخزين مؤقت

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

ما ينبغي أن يفعله التطبيق عند الرمز 1001

1. حوِّله إلى حالة واحدة في التطبيق، مثل SubscriptionExpired.
2. اعرض رسالة واضحة مفادها أن «اشتراك مؤسستك يحتاج إلى تجديد»، ووجّه المستخدم إلى المسؤول لا إلى شاشة تسجيل الدخول.
3. أوقف بدء أي عمل جديد يعتمد على الخادم.
4. احتفظ بكل البيانات المحفوظة في قائمة الانتظار. راجع العمل دون اتصال والعمليات في التطبيق.
5. لا تُخرِج المستخدم من حسابه.
6. أعد المحاولة بعد استعادة الخدمة — سيعمل التوكن الحالي.

صفحات ذات صلة

• العمل دون اتصال والعمليات في التطبيق
• ماذا يحدث عند انتهاء الاشتراك؟
• الروابط العامة وروابط العرض

راجع أيضًا قسم واجهة الجوال والباحثين لتفاصيل نقاط النهاية الخاصة بالمصادقة والاستبيانات والإرسال والمهام.