مشاركة التسجيلات · توثيق Quran Lab

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

من يقرّر

يقرّر Quran Lab ذلك من جهته، في الإعدادات الموقّعة التي يقرؤها كل تثبيت: هل يُسأل متعلّمو التطبيق أصلًا، وعلى أي منصّات. ولا يوجد في شيفرتك ولا في البوابة أي خيار يفعّل المشاركة لتطبيقك أو يعطّلها، فكل متعلّم يقرّر بنفسه.

السؤال

يعرض الـ SDK نافذته الافتراضية بلغة المتعلّم (الإنجليزية، والعربية، والإندونيسية، والأردية، والتركية، والملايوية، والفرنسية، والبنغالية) بعد محاولة مكتملة سمع فيها النموذج كلامًا، لا عند أول تشغيل أبدًا. «مشاركة تلاواتي» و«ليس الآن» لهما الوزن نفسه. يرى المتعلّم النافذة ثلاث مرات على الأكثر في التثبيت الواحد: فبعد «ليس الآن» يُعاد السؤال مرتين على الأكثر، بفاصل 7 جلسات على الأقل في كل مرة. ومن أجاب بنعم لا يُسأل مرة أخرى أبدًا.

في تطبيق موجّه للأطفال (حين يُضبط جمهور الـ SDK على الأطفال) تسأل النافذة وليّ الأمر. ولك أن تختار لحظة السؤال بنفسك (sharing.ask())، وأن تغيّر مظهر النافذة (انظر أدناه). وتعرض صفحة تطبيقك النافذة بكل اللغات.

ما الذي يُشارَك

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

كلمات النافذة هي نصوص الـ SDK: أحدثها الإصدار 2026-11-13.1 (وإصدار الموافقة share-2026-11-09)، وكل إصدار من الـ SDK يحمل النصوص التي صدر بها. والمتعلّم الذي وافق من قبل لا يُسأل مرة أخرى حين يحدّث Quran Lab هذه الكلمات، وتبقى جلساته على الإصدار الذي وافق عليه.

إلى أين يذهب

ينتقل ما يُشارَك من الجهاز مباشرة إلى تخزين Quran Lab في الاتحاد الأوروبي، ويُرفع في الخلفية، ويُستأنف رفعه بعد إعادة التشغيل. يُدار Quran Lab وقفًا: النماذج التي يدرّبها مجانية ولا تُباع أبدًا.

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

الإيقاف والحذف

حين يُطفئ المتعلّم زر التبديل يتوقف الرفع فورًا. و«احذف ما شاركته»، في صف إعدادات الـ SDK، يحذف من خوادم Quran Lab فورًا كل ما شُورِك تحت رمز المساهمة ذلك. ولا يستطيع ذلك إلا المتعلّم: فالطلب موقَّع بمفتاح توقيع لا يغادر جهازه أبدًا. والمتعلّم الذي فقد جهازه يستخدم في sdk.quranlab.ai/delete رمز الاسترداد لمرة واحدة الذي عرضه عليه الـ SDK.

أين تعمل

تعمل المشاركة في كل حزمة SDK. تُثبت تطبيقات Apple تثبيتها بخدمة App Attest، وتطبيقات Android بخدمة Google Play Integrity. أما صفحات الويب وتطبيقات Windows أو Linux فلا تستطيع إثبات تثبيتها، فتشارك بمستوى ثقة أدنى: جلسات أقل في اليوم لكل تطبيق ولكل متعلّم، وتُعلَّم جلساتها ليزنها التدريب على حدة.

في شيفرتك

تصل إلى المشاركة عبر Client، في client.sharing، ولها الأعضاء أنفسهم في كل حزمة SDK (وفي C استدعاءات tf_sharing_):

العضو	المعنى
`isAvailable`	إعدادات Quran Lab تسمح بالمشاركة لهذا التطبيق
`isOn`	وافق المتعلّم
`setOn(on)`	زر التبديل الخاص بالمتعلّم في إعدادات تطبيقك، ولا يُستدعى إلا منه. إطفاؤه يوقف الرفع فورًا ويحذف قائمة الانتظار التي لم تُرسَل بعد
`ask()`	يسأل الآن، في اللحظة التي تختارها، إن كان السؤال ما زال مسموحًا
`feed(samples, sampleRate)`	صوت يلتقطه تطبيقك أصلًا خارج المحاولات، حتى لا يبدأ التسجيل المُشارَك أو ينتهي في وسط كلمة
`items`	صندوق الصادر: حالة كل تسجيل
`summary()`	ملخّص المتعلّم، لسطر شكر
`delete()`	«احذف ما شاركته»
`recoveryCode`	رمز الحذف عند فقد الجهاز
`setWording(overrides)`	كلماتك أنت لأي سطر في النافذة

إذا لم تسمح إعدادات Quran Lab بالمشاركة للتطبيق، فإن أي استدعاء للمشاركة يفشل برمز الخطأ sharing_unavailable: تحقّق من isAvailable قبل أن تعرض إعدادات المشاركة.

اجعل النافذة تبدو كتطبيقك

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

خصّص مظهر النافذة الافتراضية. تغيّر الألوان والخطوط والزوايا، أما الكلمات وإصدار الموافقة فلا تتغيّر. على الويب تقرأ النافذة خصائص CSS المخصّصة (custom properties):

quranlab-consent {
  --ql-bg: #fff; --ql-fg: #1d1d1f; --ql-muted: #6e6e73;
  --ql-accent: #0f766e; --ql-accent-fg: #fff;
  --ql-radius: 20px; --ql-font: inherit;
}

على Android و Apple يؤدّي SharingTheme الأمر نفسه لنافذة الـ SDK نفسها ولصفوف إعداداته. ومكتبة C لا ترسم نافذة: يعرضها تطبيقك من النصوص التي يسلّمها الـ SDK إلى دالة رد النداء (callback) الخاصة بالموافقة.

شاشتك الخاصة، المبنية من نصوص الـ SDK: الأسطر نفسها بكل لغة يحملها الـ SDK. أبلغ الـ SDK بالنقرة التي نقرها المتعلّم نفسه. وتُحتسب شاشتك الخاصة كما تُحتسب نافذة الـ SDK: مرات السؤال نفسها، وقواعد «ليس الآن» نفسها، ولا يُسجَّل شيء قبل أن يوافق المتعلّم بنفسه.

كلماتك أنت. يأخذ setWording كلماتك لأي سطر في النافذة، وتُضبط عند كل بدء تشغيل. وعندئذٍ يوافق المتعلّم على كلماتك أنت: فكل جلسة يشاركها تحمل إصدارًا مشتقًّا منها (custom- ثم 24 رقمًا ست عشريًا) وبصمة SHA-256 للنص الكامل، فيرى Quran Lab بالضبط ما وافق عليه المتعلّم. يعطيك الـ SDK هذا النص وبصمته، فأرسلهما إلى Quran Lab للمراجعة (يدوّنهما مساعدك البرمجي مع إقرار تطبيقك). ويجب مع ذلك أن تذكر كلماتك أن صوت جلسات التلاوة يذهب إلى Quran Lab، وما الذي يُرسَل غيره، والغرض من ذلك، وطريقة الإيقاف والحذف. والمتعلّم الذي وافق من قبل لا يُسأل مرة أخرى، ويبقى على الإصدار الذي وافق عليه.

تجد الأسماء الدقيقة لإصدار الـ SDK لديك في README الخاص به.