نشر الإضافة

توضّح هذه الصفحة كيفية نشر إضافة على "مركز الإضافات".

قبل البدء

لنشر إضافة، عليك أولاً التسجيل كناشر إضافات.

المصادر القابلة للتحقّق

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

ويعني ذلك حاليًا إتاحة رمز المصدر الخاص بالإضافة على مستودع GitHub عام.

تتوفّر عدة مزايا عند التحميل من مصدر يمكن التحقّق منه:

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

دورة التطوير المقترَحة

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

تتيح هذه الإمكانية دورة تطوير على النحو التالي:

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

  2. اختبِر الإضافة في مشروع حقيقي من خلال تثبيتها من مصدر محلي:

    firebase ext:install /path/to/extension
firebase deploy --only extensions

  3. حمِّل إصدارًا مسبقًا إلى "مركز الإضافات" (راجِع ما يلي). وزِّع رابط التثبيت لإجراء اختبار أوسع نطاقًا، وكرِّر العملية عن طريق تحميل المزيد من الإصدارات التجريبية حسب الحاجة.

  4. حمِّل الإصدار النهائي والثابت إلى "مركز الإضافات" (انظر أدناه) وأرسِله للمراجعة. إذا اجتازت الإضافة عملية المراجعة، سيتم نشرها في "مركز الإضافات".

  5. عليك زيادة رقم الإصدار في extension.yaml وتكرار هذه الدورة للإصدار التالي من الإضافة.

تحميل إضافة جديدة

لتحميل إضافة للمرة الأولى، اتّبِع الخطوات التالية:

  1. اختياري: يمكنك إرسال الرمز البرمجي إلى مستودع GitHub عام.

  2. نفِّذ الأمر ext:dev:upload في واجهة سطر الأوامر (CLI) الخاصة بخدمة Firebase:

    GitHub

    firebase ext:dev:upload your_publisher_id/your_extension_id

    المصدر المحلي

    cd /path/to/extension
firebase ext:dev:upload your_publisher_id/your_extension_id --local

    في استدعاء الأمر، عليك تحديد ما يلي:

    • رقم تعريف الناشر الذي سجّلته.

    • سلسلة معرّف تحدّد الإضافة. سمِّ إضافاتك بالتنسيق التالي: firebase-product-description-of-tasks-performed. على سبيل المثال: firestore-bigquery-export

    سيطلب منك الأمر تقديم معلومات إضافية:

    • إذا كنت تحمّل من GitHub:

      • عنوان URL الخاص بمستودع الإضافة في GitHub يُرجى العِلم أنّ المستودع يمكن أن يحتوي على عدة إضافات ما دام لكل إضافة جذر فريد.

        عند تحميل إضافة جديدة للمرة الأولى، سيتم تسجيل المستودع كمصدر أساسي للإضافة.

      • الدليل في المستودع الذي يحتوي على الإضافة

      • مرجع Git لعملية الإيداع التي تريد إنشاء إصدار إضافة من مصدرها. يمكن أن يكون هذا المعرّف عبارة عن تجزئة عملية إيداع أو علامة أو اسم فرع.

    • مرحلة إصدار النسخة التي تحمّلها

      تُستخدَم مراحل alpha وbeta وrc (الإصدار التجريبي) لتحميل إصدارات ما قبل الإصدار ليتمكّن المختبِرون من تثبيتها. استخدِم إحدى هاتين المرحلتين لتحميل إضافة جديدة في البداية.

      يتم استخدام مرحلة stable لنشر الإصدارات المتاحة للجميع على "مركز الإضافات". سيؤدي تحميل إصدار stable إلى بدء عملية مراجعة تلقائيًا، وإذا اجتازت المراجعة، سيتم نشر الإضافة.

    لاحظ أنّه لا يتم تحديد رقم إصدار، بل يتم استخراجه من ملف extension.yaml. عند تحميل إصدار تجريبي من إضافة، تتم إضافة المرحلة ورقم التحميل إلى الإصدار. على سبيل المثال، إذا كان extension.yaml يحدّد الإصدار 1.0.1 وحمّلت إصدارًا تجريبيًا، سيؤدي ذلك إلى الإصدار 1.0.1-rc.0، وسيؤدي تحميل إصدار تجريبي آخر من الإصدار نفسه إلى زيادة العدد تلقائيًا، ما يؤدي إلى الإصدار 1.0.1-rc.1، وهكذا.

بعد تحميل إصدار تجريبي من الإضافة، يمكنك مشاركته مع الآخرين لاختباره. يمكن للمستخدمين تثبيت الإضافة بإحدى الطريقتَين التاليتَين:

  • باستخدام وحدة التحكّم: يمكن للمستخدمين تثبيت الإضافة من خلال النقر على رابط بالتنسيق التالي:

    https://console.firebase.google.com/project/_/extensions/install?ref=your_publisher_id/your_extension_id@version

    يمكنك مشاركة الرابط المباشر مع المختبِرين.

  • باستخدام واجهة سطر الأوامر: يمكن للمستخدمين تثبيت الإضافة من خلال تمرير سلسلة معرّف الإضافة إلى الأمر ext:install:

    firebase ext:install your_publisher_id/your_extension_id@version \
    --project=destination_project_id

تحميل نسخة معدَّلة

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

لتحميل تحديث:

  1. اختياري: يمكنك إرسال الرمز إلى مستودع Git عام.

  2. نفِّذ الأمر ext:dev:upload في واجهة سطر الأوامر (CLI) الخاصة بخدمة Firebase:

    GitHub

    firebase ext:dev:upload your_publisher_id/your_extension_id

    في هذه المرة، لن يُطلب منك تحديد مستودع GitHub أو الدليل الجذر للإضافة، لأنّهما سبق أن تم إعدادهما للإضافة. إذا كنت قد أعدت تصميم بنية المستودع أو نقلت البيانات إلى مستودع جديد، يمكنك تغييرها باستخدام وسيطتَي الأمر --root و--repo.

    المصدر المحلي

    cd /path/to/extension
firebase ext:dev:upload your_publisher_id/your_extension_id --local

إرسال إضافة لنشرها

عندما تصبح مستعدًا لإصدار الإضافة بشكل علني، اتّبِع الخطوات التالية:

  1. احفظ الرمز البرمجي في مستودع Git علني. (مطلوب للإصدارات المتاحة للجميع)

  2. نفِّذ الأمر ext:dev:upload في واجهة سطر الأوامر الخاصة بمنصة Firebase، مع تحديد stable كمرحلة الإصدار:

    firebase ext:dev:upload your_publisher_id/your_extension_id

  3. إذا سبق لك نشر إصدار من الإضافة، سيؤدي تحميل إصدار ثابت جديد إلى إرسال الإضافة تلقائيًا للمراجعة.

    إذا حمّلت الإصدار الثابت الأول من الإضافة، ابحث عن الإضافة في لوحة بيانات الناشر، ثم انقر على نشر في "مركز إضافات Chrome".

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

لتسريع عملية المراجعة وزيادة فرص اجتيازها في المحاولة الأولى، يُرجى التحقّق مما يلي قبل إرسال الطلب:

  • اختبرت الإضافة وعملية التثبيت بشكلٍ كامل.
  • المستندات كاملة وصحيحة، ويتم عرضها بشكل جيد في وحدة تحكّم Firebase.
  • يجب أن يحدّد اسم الناشر وعلامته التجارية هويتك بوضوح ودقة كناشر.
  • يجب أن يوضّح اسم الإضافة ووصفها ورمزها الغرض من الإضافة بدقة.
  • لقد طبّقت علامات مفيدة ودقيقة.
  • لقد أدرجت في extension.yaml جميع واجهات برمجة التطبيقات التي تستخدمها، سواء كانت من Google أو من جهات أخرى، وجميع أنواع الأحداث التي تنشئها الإضافة.
  • أنّك تطلب الوصول إلى الأدوار الضرورية فقط لكي تعمل الإضافة، وأنّك وضّحت للمستخدمين بوضوح سبب حاجتك إلى هذا الوصول.
  • ملفات المصدر مرخَّصة بوضوح بموجب بنود Apache-2.0.

إدارة الإضافات التي تم تحميلها ونشرها

إدراج إضافاتك التي تم تحميلها

لعرض الإضافات التي حمّلتها ضمن رقم تعريف الناشر، اتّبِع أحد الإجراءَين التاليَين:

لوحة بيانات الناشر

يمكنك الاطّلاع عليها في لوحة بيانات الناشر.

Firebase CLI

نفِّذ الأمر ext:dev:list:

firebase ext:dev:list your_publisher_id

عرض استخدام الإضافات التي حمّلتها

لعرض استخدام الإضافات التي حمّلتها ضمن رقم تعريف الناشر، اتّبِع إحدى الخطوات التالية:

لوحة بيانات الناشر

تتضمّن لوحة بيانات الناشر مقاييس الاستخدام التراكمية لجميع إضافاتك ومقاييس فردية لكل إضافة.

Firebase CLI

نفِّذ الأمر ext:dev:usage:

firebase ext:dev:usage your_publisher_id

إيقاف إصدار إحدى الإضافات نهائيًا

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

لإيقاف إصدار من إضافة، اتّبِع أحد الإجراءات التالية:

لوحة بيانات الناشر

  1. في لوحة بيانات الناشر، انقر على الإضافة لفتح عرض التفاصيل.
  2. اختَر الإصدار الذي تريد إيقافه نهائيًا.
  3. انقر على إيقاف الإصدار نهائيًا.

Firebase CLI

نفِّذ الأمر ext:dev:deprecate:

firebase ext:dev:deprecate your_publisher_id/your_extension_id versions \
    [--message "deprecation_message"]

يمكنك تحديد إصدار واحد أو نطاق من الإصدارات. أمثلة:

  • 1.0.2
  • 1.1.0-1.1.7
  • <1.2.0
  • 1.1.*

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

إذا تم إيقاف جميع إصدارات إضافة معيّنة، سيتم اعتبارها متوقفة وستتم إزالتها من &quot;مركز الإضافات&quot;. سيؤدي تحميل إصدار جديد من إضافة تم إيقافها نهائيًا إلى بدء عملية مراجعة تلقائيًا، وبعد قبولها، سيتم نشرها على "مركز الإضافات" مرة أخرى.

لإلغاء الإيقاف النهائي، استخدِم لوحة بيانات الناشر أو شغِّل الأمر ext:dev:undeprecate في واجهة سطر الأوامر (CLI) الخاصة بمنصة Firebase:

firebase ext:dev:undeprecate your_publisher_id/your_extension_id versions

الملحق: تحديد مشاكل أخطاء الإصدار وحلّها

عند تحميل الإضافة، ينشئ الخلفية رمز المصدر أولاً باتّباع العملية التالية:

  1. يستنسخ مستودع GitHub ويتحقّق من مرجع المصدر المحدّد.

  2. تثبِّت هذه السمة حِزم NPM التابعة من خلال تنفيذ npm clean-install في كل دليل مصدر للدالة محدّد في extension.yaml (راجِع sourceDirectory في موارد Cloud Functions).

    لاحظ ما يلي:

    • يجب أن يتضمّن كل ملف package.json ملف package-lock.json مطابقًا. لمزيد من المعلومات، يُرجى الاطّلاع على npm-ci.

    • لن يتم تشغيل البرامج النصية بعد التثبيت أثناء تثبيت التبعيات. إذا كان إصدار الرمز المصدر يعتمد على نصوص برمجية بعد التثبيت، عليك إعادة تصميمه قبل تحميله.

  3. تنشئ هذه السمة الرمز البرمجي من خلال تنفيذ npm run build في كل دليل لمصدر دالة محدّد في extension.yaml.

سيتم حفظ دليل الجذر للإضافة فقط في حزمة الإضافة النهائية التي ستتم مشاركتها.

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