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

يجب أن تحتوي كل إضافة على مستندات تعلم المستخدمين ما هي الإضافة وكيفية استخدامها.

الحد الأدنى من المستندات المطلوبة هو هذه المجموعة المكونة من ثلاثة ملفات 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 الإبلاغ عن --markdown > README.md)

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

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

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

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

ننصح باستخدام أكبر قدر ممكن من النص النموذجي التالي، ينطبق على الإضافة. لقد قدّمنا بعض الأمثلة، ولكن النقطة الأكثر أهمية هي التأكّد من إدراج جميع الخدمات التي يتم تحصيل رسومها من Google والخدمات التي لا تتبع 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 بعد تثبيت المستخدم لإضافة Chrome (في بطاقة تفاصيل الإضافة المثبّتة)

  • احرص على مراجعة عرض محتوى "POSTINSTALL" بحلول تثبيت الإضافة بشكل فعلي مشروعك.

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

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

ما هي أفضل الممارسات لحل هذه المشكلة؟

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

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

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

ملاحظة: بالنسبة إلى القيم التي يمكن أن تكون طويلة (مثل مسار قاعدة بيانات أو عنوان URL لدالة)، يمكنك الإشارة إلى المَعلمة أو المتغيّر في نهاية الجمل والأقسام. تسهّل هذه أفضل الممارسات قراءة الجمل فيconsole 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 وواجهة سطر الأوامر سوى التغييرات التي ستسري إذا أكمل المستخدم عملية الترقية.
• مستودع رمز المصدر للإضافة (داخل دليل الإضافات).