المفاتيح

يربط المفتاح التطبيق بمساحة عملك في sdk.quranlab.ai. ينشئ زر «انسخ التعليمات» مفتاحًا لك ويسلّمه إلى مساعدك البرمجي. ويمكنك أيضًا إنشاء مفتاح يدويًا في صفحة المفاتيح.

ما يفعله المفتاح

بهذا المفتاح يتولّى الـ SDK بنفسه ما يلي:

• يسجّل التطبيق عند أول تشغيل له، فيظهر في صفحة التطبيقات دون أن تملأ أي شيء؛
• يجلب الإعدادات الموقّعة للتطبيق (توقيع Ed25519 يُتحقَّق منه بمفتاح تحقّق مضمَّن في الـ SDK) عند التشغيل، وحين ينتقل التطبيق إلى الواجهة، وكل دقيقة أثناء استخدامه، فيصل ما تغيّره في sdk.quranlab.ai إلى التطبيقات العاملة في غضون دقيقة تقريبًا؛
• لا يُنزّل من ملفات النموذج إلا ما يحتاجه جهازه، ويطابق كل ملف مع البيان الموقّع، ويحتفظ بالمحرّك الدقيق على المعالج المركزي للرجوع إليه، ولا ينتقل إلى إصدار جديد من النموذج أو إلى حزمة جديدة منه إلا في بداية جلسة؛
• يرسل عدّادات يومية مجهولة الهوية (كل حقل)، وبلاغات المشكلات المجمّعة.

الأنواع

يُختار نوع المفتاح عند إنشائه، ولا يتغيّر أبدًا.

مفتاح الويب عامّ بحكم تصميمه: لا يعمل إلا من الأصول التي حدّدتها له، ويُسجَّل كل أصل منها تطبيقًا مستقلًا. ويمكن تقييد مفتاح تطبيقات أو مفتاح سطح مكتب بمعرّف تطبيقك، فلا ينفع المفتاح المنسوخ في أي تطبيق آخر.

المفتاح إمّا للإنتاج وإمّا للتطوير. ومن الطبيعي أن يكون للتطبيق الواحد مفتاح تطوير ومفتاح إنتاج. ولا يُحتسب مفتاح التطوير أبدًا في إحصاءات الإنتاج.

مكان المفتاح

القاعدة الإرشادية مفتاح واحد لكل تطبيق. ويُعرض المفتاح كاملًا مرة واحدة، عند إنشائه. أبقِه خارج مستودعك: في ملف properties خارج git على Android، وفي ملف xcconfig على Apple، وفي ملف البيئة على الويب، وفي متغيّرات البيئة أو ملف إعداد تطبيقك على Windows و Linux. وتُبيّن كل صفحة من صفحات البدء السريع هذا المكان.

تدوير المفتاح وحذفه

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

دوّر المفتاح حين يجب أن يتوقف الآن، كأن يكون قد تسرّب. ولتغيّر المفتاح دون أن تقطع التثبيتات:

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

إذا لم يعد الخادم يعرف المفتاح، فرمز الخطأ في الـ SDK هو invalid_key.

حين يرفض الخادم مفتاحًا أو تطبيقًا

يرفض الخادم التثبيت في هذه الحالات:

• حُذف مفتاحه أو دُوِّر، أو لا وجود له؛
• لا يذكر المفتاح معرّف التطبيق، أو أصل الصفحة (origin)؛
• نوع المفتاح لا يناسب المنصة؛
• أوقفت التطبيق مؤقتًا، أو حظره Quran Lab؛
• لم يعد للحساب الذي يملك المفتاح وصول إلى Quran Lab.

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

وحين يقبل الخادم المفتاح من جديد (تعيد التطبيق إلى العمل، أو تعيد المعرّف إلى المفتاح، أو يثبّت المتعلّم تحديثًا بمفتاح صالح)، يُنزّل التثبيت النموذج مرة أخرى كما في التثبيت الأول: نحو 57 ميغابايت.

رمز الخطأ في الـ SDK هو invalid_key للمفتاح المحذوف أو المُدوَّر أو غير المعروف، و server_rejected للحالات الأخرى، مع السبب: app_not_allowed أو origin_not_allowed أو key_type_mismatch أو app_blocked أو developer_not_approved.

في المؤسسة

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