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

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

الحد الأدنى من المستندات المطلوبة هو هذه المجموعة من ملفات 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)
  • وصف موجز لأيّ تأثيرات للفوترة (ابدأ بعبارة مكرّرة)

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

صورة لمحتوى التثبيت المُسبَق في <span class=وحدة تحكُّم Firebase">
تثبيت المحتوى مسبقًا في وحدة تحكُّم Firebase

صورة كبيرة لمحتوى ما قبل التثبيت في <span class=وحدة تحكّم Firebase">

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

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

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

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

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

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

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

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
  • إرشادات موجزة حول كيفية مراقبة الإضافة المثبَّتة (ابدأ بعبارة نموذجية)

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

صورة لمحتوى ما بعد التثبيت في <span class=وحدة تحكُّم Firebase">
المحتوى بعد التثبيت في وحدة تحكُّم Firebase

صورة كبيرة لمحتوى ما بعد التثبيت في <span class=وحدة تحكّم Firebase">

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

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

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

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

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

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

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

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

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

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.

توثيق كيفية بدء إضافة

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

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

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

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

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

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

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

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

إنّ النقاط التالية هي نص نموذجي مقترَح لتضمينه في ملفPOSTINSTALL الإضافة. بعد التثبيت، Firebase console تعرض محتوى ملف 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}`**.

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