إنشاء مستندات المستخدم للإضافة

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

المستندات المطلوبة كحدّ أدنى هي مجموعة ملفات Markdown الثلاثة التالية:

• PREINSTALL.md
• POSTINSTALL.md
• CHANGELOG.md

بالإضافة إلى ذلك، ننصحك أيضًا بإنشاء ما يلي:

• ملف README للمستودع العلني للإضافة
• البرامج التعليمية والأدلّة والمراجع الطويلة التي يتم نشرها على موقعك الإلكتروني وربطها في PREINSTALL.md

للتعرّف على بعض أفضل الممارسات والصياغة والبنية الشائعة، ننصحك بمراجعة الملفات المتاحة مع إضافات Firebase الرسمية.

إنشاء ملف README

يمكن أن يحتوي دليل الإضافة اختياريًا على ملف README. يُرجى العلم أنّ الأمر firebase ext:dev:init لا ينشئ تلقائيًا ملفًا لك.

مع ذلك، تتيح واجهة سطر الأوامر Firebase استخدام أمر مناسب لتنفيذ ما يلي: إنشاء ملف README تلقائيًا يتضمّن محتوى تم استخراجه من ملف extension.yaml وملف PREINSTALL.md:

firebase ext:info ./path/to/extension --markdown > README.md

يتم إنشاء جميع ملفات README الخاصة بالإضافات Firebaseالرسمية باستخدام هذا الأمر.

إضافة معلومات التثبيت

بعد كتابة ملف README أو إنشائه، أضِف معلومات التثبيت إليه. يمكنك استخدام المقتطف التالي كنموذج:

---

## 🧩 Install this extension

### Console

[![Install this extension in your Firebase project](https://www.gstatic.com/mobilesdk/210513_mobilesdk/install-extension.png "Install this extension in your Firebase project")][install-link]

[install-link]: https://console.firebase.google.com/project/_/extensions/install?ref=publisher_id/extension_name

### Firebase CLI

```bash
firebase ext:install publisher_id/extension_name --project=[your-project-id]
```

> Learn more about installing extensions in the Firebase Extensions documentation:
> [console](https://firebase.google.com/docs/extensions/install-extensions?platform=console),
> [CLI](https://firebase.google.com/docs/extensions/install-extensions?platform=cli)

---

كتابة ملف PREINSTALL

ملف PREINSTALL هو نظرة عامة على إضافتك، وهو نوع من صفحات "التسويق".

ما هو المحتوى الموجود في هذا الملف؟

• وصف شامل لوظائف الإضافة
• قائمة بالمتطلبات الأساسية، مثل إعداد قاعدة البيانات أو الوصول إلى خدمة غير تابعة لـ Google (مثال)
• وصف موجز لأي مهام ما قبل التثبيت وتعليماتها
• وصف موجز لأي مهام بعد التثبيت (مثال) (يتم إدراج التعليمات التفصيلية في POSTINSTALL)
• وصف موجز لأي آثار على الفوترة (ابدأ بـ نص نموذجي)

أين يظهر هذا المحتوى للمستخدم؟

وحدة تحكّم Firebase">

المحتوى المثبَّت مسبقًا في Firebase وحدة التحكّم

وحدة تحكّم Firebase">

• في صفحة الإضافة على extensions.dev
• مستودع رمز المصدر الخاص بالإضافة (داخل دليل الإضافة)
• كجزء من ملف README الخاص بالإضافة (إذا كنت تستخدم العلامة Firebase CLI --markdown > README.md)

لا يمكن لملفات PREINSTALL الوصول إلى قيم المَعلمات الخاصة بالإضافة، لذا يجب عدم توقّع عرض مراجع المَعلمات مع القيم الفعلية.

ما هي بعض أفضل الممارسات؟

• حاوِل إبقاء المحتوى الكامل لملف PREINSTALL في صفحة واحدة، إذا أمكن ذلك
• قدِّم مستوى التفاصيل التي يحتاج المستخدم النهائي إلى معرفتها قبل تثبيت الإضافة
• وضع تعليمات مفصّلة في ملف POSTINSTALL أو ملفات تكميلية أخرى
• اذكر بإيجاز ما إذا كنت توفّر أدوات أو نصوصًا برمجية أخرى لدعم الإضافة.

نص نموذجي مفيد PREINSTALL

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

يمكنك استخدام المَراجع التالية للعثور على تفاصيل تسعير المنتج الصحيحة:

• قائمة أسعار منتجات Google Cloud
• نظرة عامة على أسعار Firebase

بالنسبة إلى جميع الإضافات، يجب تضمين هذا القسم لمساعدة المستخدمين على فهم الآثار المترتبة على الفوترة:

Billing

This extension uses other Firebase or Google Cloud services which may have
  associated charges:

*   <list Google services / products that your extension uses>
*   <list Firebase services that your extension uses>
*   Cloud Secret Manager <if the extension uses secret params>
*   Cloud Functions

When you use Firebase Extensions, you're only charged for the underlying
resources that you use. A paid-tier billing plan is only required if the
extension uses a service that requires a paid-tier plan, for example calling to
a Google Cloud API or making outbound network requests to non-Google services.
All Firebase services offer a no-cost tier of usage.
[Learn more about Firebase billing.](https://firebase.google.com/pricing)

<Applicable info about billing implications for non-Google services, such as:>
Usage of this extension also requires you to have a <non-Google-service> account.
You are responsible for any associated costs with your usage of <non-Google-service>.

كتابة ملف POSTINSTALL

ملف POSTINSTALL هو صفحة تعليمات مفصّلة تظهر بعد تثبيت الإضافة.

ما هو المحتوى الموجود في هذا الملف؟

• تعليمات مفصّلة بشأن أي مهام مطلوبة بعد التثبيت، مثل إعداد قواعد الأمان في Firebase أو إضافة رمز برمجي من جهة العميل (مثال)
• تعليمات عامة حول كيفية تجربة الإضافة المثبّتة على الفور (مثلاً، "انتقِل إلى وحدة التحكّم، ثمّ اتّبِع الخطوات التالية")
• معلومات أساسية حول كيفية تشغيل الإضافة، خاصةً الإضافات التي يتم تشغيلها بطلب HTTP
• تعليمات موجزة حول كيفية مراقبة الإضافة المثبَّتة (ابدأ بـ النص النموذجي)

أين يظهر هذا المحتوى للمستخدم؟

وحدة تحكّم Firebase">

المحتوى بعد التثبيت في Firebase وحدة التحكّم

وحدة تحكّم Firebase">

• في وحدة تحكّم Firebase بعد أن يثبّت المستخدم إضافتك (في بطاقة التفاصيل الخاصة بالإضافة المثبّتة)

  • احرص على مراجعة طريقة عرض محتوى POSTINSTALL من خلال تثبيت الإضافة في مشروع فعلي.

• مستودع رمز المصدر الخاص بالإضافة (داخل دليل الإضافة)

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

ما هي بعض أفضل الممارسات؟

• يجب أن يكون المحتوى الكامل لملف POSTINSTALL موجزًا ووصفيًا في الوقت نفسه.
• قسِّم المحتوى باستخدام العناوين لفصل المهام أو المفاهيم المميّزة.
• ننصحك بنشر تعليمات مفصّلة لسير عمل أو مهمة معيّنة على موقعك الإلكتروني (مثال) أو في ملفات markdown تكميلية ضمن مستودع الإضافة (مثال).
• الإشارة إلى المَعلمات المرجعية والمتغيّرات ذات الصلة بالدالة حتى يرى المستخدم القيم التي تم ضبطها في سياق التعليمات

الإشارة إلى المَعلمات والمتغيّرات

بعد التثبيت، تعرض وحدة تحكّم Firebase محتوى ملف POSTINSTALL الخاص بالإضافة. إذا أشرت إلى مَعلمات ومتغيّرات ذات صلة بالدالة (راجِع الجدول أدناه) في ملف POSTINSTALL، ستملأ وحدة التحكّم هذه المراجع بالقيم الفعلية للمثيل المثبَّت.

ملاحظة: بالنسبة إلى القيم التي يمكن أن تكون طويلة (مثل مسار قاعدة بيانات أو عنوان URL لدالة)، يجب الإشارة إلى المَعلمة أو المتغيّر في نهاية الجُمل والأقسام. تسهّل هذه الممارسة قراءة الجُمل في وحدة تحكّم Firebase عندما يتم عرض محتوى ملف POSTINSTALL بالقيم الفعلية.

يمكنك الوصول إلى قيم المَعلمات التي تم ضبطها في الملف POSTINSTALL باستخدام الصيغة التالية: ${param:PARAMETER_NAME}

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

في هذا الجدول، function-name هي قيمة الحقل name في عنصر المورد الخاص بالدالة ضمن extension.yaml.

مرجع للمتغيرات ذات الصلة بالدالة	الوصف	قيمة المتغيّر (تتم تعبئتها تلقائيًا من خلال Firebase بعد تثبيت الإضافة)
${function:function-name.location}
	الموقع الجغرافي الذي يتم فيه نشر الدالة	مثال على القيمة: us-central1
${function:function-name.name}
	اسم الدالة المنشورة النهائية، والذي يتضمّن رقم تعريف مثيل الإضافة	التنسيق العام: ext-extension-instance-id-function-name مثال على القيمة: ext-my-awesome-extension-6m31-yourFunctionName
${function:function-name.url} (ينطبق فقط على دوال HTTP)
	عنوان URL للدالة المنشورة النهائية التي يمكن لرمز العميل إرسال طلبات HTTP إليها	التنسيق العام: https://deployment-location-project-id.cloudfunctions.net/name-of-final-deployed-function مثال على القيمة: https://us-central1-project-123.cloudfunctions.net/ext-my-awesome-extension-6m31-yourFunctionName

نص نموذجي مفيد POSTINSTALL

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

بالنسبة إلى جميع الإضافات، أدرِج القسم التالي لمساعدة المستخدمين في تتبُّع الإضافة المثبَّتة:

Monitoring

As a best practice, you can
[monitor the activity](https://firebase.google.com/docs/extensions/manage-installed-extensions_community#monitor)
of your installed extension, including checks on its health, usage, and logs.

توثيق كيفية تشغيل إضافة

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

الإضافات التي يتم تشغيلها في الخلفية استنادًا إلى الأحداث

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

إجراء تغييرات مباشرة في وحدة التحكّم

يمكنك توجيه المستخدمين لإجراء تغييرات تؤدي إلى تشغيل الإضافة مباشرةً في وحدة تحكّم Firebase، خاصةً عند اختبار الإضافة لأول مرة. على سبيل المثال، لنفترض أنّ إضافتك تنشئ مستند Cloud Firestore جديدًا كلما تم إنشاء مستخدم Firebase Authentication جديد. يمكنك توجيه المستخدمين لاختبار نسخة مثبَّتة من الإضافة عن طريق إضافة Authentication مستخدم جديد يدويًا في وحدة التحكّم. يمكنهم بعد ذلك ملاحظة المستند الجديد الذي تم إنشاؤه في قسم Cloud Firestore من وحدة التحكّم.

إضافة رمز من جهة العميل

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

الإضافات التي يتم تشغيلها عند تلقّي طلب HTTP

لكي يتمكّن المستخدمون من تشغيل دالة يتم تشغيلها بطلب HTTP (وبالتالي تشغيل الإضافة)، عليك تزويدهم باسم الدالة المنشورة أو عنوان URL الخاص بها.

اسم الدالة النهائية التي تم نشرها ليس هو نفسه name الذي حدّدته في عنصر مورد الدالة ضمن extension.yaml. لاستيعاب عمليات تثبيت متعددة للإضافة نفسها في أحد المشاريع، تعيد Firebase تسمية الدالة بهذا التنسيق: ext-extension-instance-id-function-name.

في ما يلي نص نموذجي مقترَح لتضمينه في ملف POSTINSTALL الخاص بالإضافة. بعد التثبيت، تعرض وحدة تحكّم Firebase محتويات الملف POSTINSTALL وتملأ هذه المراجع بالقيم الفعلية التي تم ضبطها للمثيل المثبَّت. على سبيل المثال، إذا عرّفت دالة باسم yourFunction، يمكنك تضمين ما يلي (حسب الاقتضاء):

• بالنسبة إلى دوال HTTP onRequest

  To trigger this extension, make a request to or visit the following URL:
  **`${function:yourFunction.url}`**.
  

• بالنسبة إلى الدوال القابلة للاستدعاء عبر HTTP (onCall)

  This extension is implemented as an HTTP callable function. To call it from your client app,
  follow the instructions in the
  [callable functions documentation](https://firebase.google.com/docs/functions/callable#call_the_function).
  The name of the function to call is **`${function:yourFunction.name}`**,
  and its region is **`${function:yourFunction.location}`**.
  

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

كتابة ملف CHANGELOG

ما هو المحتوى الموجود في هذا الملف؟

يجب أن يتضمّن كل إضافة ملف CHANGELOG.md يوثّق التغييرات المضمّنة في كل إصدار جديد تنشره من الإضافة. ضَع كل إصدار ضمن عنوان من المستوى 2 (##)، وإلا يمكنك استخدام أي تنسيق Markdown تريده.

المثال التالي هو مقتطف من إحدى الإضافات الرسمية:

## Version 0.1.3

feature - Support deletion of directories (issue #148).

## Version 0.1.2

feature - Add a new param for recursively deleting subcollections in Cloud
Firestore (issue #14).

fixed - Fixed "cold start" errors experienced when the extension runs after a
period of inactivity (issue #48).

## Version 0.1.1

Initial release of the _Delete User Data_ extension.

أين يظهر هذا المحتوى للمستخدم؟

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