يجب أن يحتوي كل ملحق على وثائق تعلم المستخدمين ما يفعله الملحق وكيفية استخدامه.
الحد الأدنى المطلوب من الوثائق هو هذه المجموعة المكونة من ثلاثة ملفات تخفيض السعر:
-
PREINSTALL.md -
POSTINSTALL.md -
CHANGELOG.md
بالإضافة إلى ذلك، يجب عليك أيضًا التفكير في إنتاج:
- ملف
READMEللمستودع العام للامتداد. - تم نشر البرامج التعليمية والأدلة والمراجع الأطول على موقع الويب الخاص بك وربطها في
PREINSTALL.mdالخاص بك.
للتعرف على بعض أفضل الممارسات والصياغة والبنية الشائعة، نوصي بمراجعة الملفات المتوفرة مع ملحقات Firebase الرسمية .
إنشاء الملف التمهيدي
يمكن أن يحتوي دليل الامتداد الخاص بك اختياريًا على ملف README. لاحظ أن أمر firebase ext:dev:init لا يقوم تلقائيًا بإنشاء أمر لك.
ومع ذلك، يدعم Firebase CLI الأمر الملائم التالي لإنشاء ملف README تلقائيًا الذي يحتوي على محتوى تم سحبه من ملف extension.yaml وملف PREINSTALL.md :
firebase ext:info ./path/to/extension --markdown > README.md
يتم إنشاء جميع ملفات README الخاصة بامتدادات Firebase الرسمية باستخدام هذا الأمر.
إضافة معلومات التثبيت
بعد كتابة ملف README أو إنشائه، قم بإضافة معلومات التثبيت إليه. يمكنك استخدام المقتطف التالي كقالب:
--- ## 🧩 Install this extension ### Console [][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) - وصف موجز لأية آثار متعلقة بالفوترة (ابدأ بالنص المعياري )
أين يظهر هذا المحتوى للمستخدم؟
- في صفحة الامتداد على الامتدادات.dev .
- مستودع التعليمات البرمجية المصدر الخاص بك لامتدادك (داخل دليل الامتداد)
- كجزء من ملف README الخاص بالامتداد (إذا كنت تستخدم Firebase CLI
--markdown > README.md
لا يمكن لملفات PREINSTALL الوصول إلى قيم المعلمات الخاصة بالامتداد، لذلك لا تتوقع أن يتم عرض مراجع المعلمات بقيم فعلية.
ما هي بعض أفضل الممارسات؟
- احتفظ بالمحتوى الكامل لملف
PREINSTALLفي صفحة واحدة ، إن أمكن - قم بتوفير مستوى التفاصيل التي يحتاج المستخدم النهائي إلى معرفتها قبل تثبيت الامتداد
- ضع تعليمات مفصلة في ملف
POSTINSTALLأو الملفات التكميلية الأخرى - أذكر بإيجاز ما إذا كنت تقدم أدوات أو نصوص برمجية أخرى لدعم الامتداد
نوصي باستخدام أكبر قدر ممكن من النص المعياري التالي، حسب ما ينطبق على ملحقك. لقد قدمنا بعض الأمثلة، ولكن النقطة الأكثر أهمية هي التأكد من إدراج جميع الخدمات التي يتم تحرير فواتير من Google وغير التابعة لها.
يمكنك استخدام الموارد التالية للعثور على تفاصيل تسعير المنتج الصحيحة:
بالنسبة لجميع الإضافات، قم بتضمين هذا القسم لمساعدة المستخدمين على فهم الآثار المترتبة على الفوترة:
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 بعد أن يقوم المستخدم بتثبيت الامتداد الخاص بك (في بطاقة تفاصيل الامتداد المثبت)
- تأكد من مراجعة عرض محتوى
POSTINSTALLعن طريق تثبيت الامتداد الخاص بك في مشروع فعلي .
- تأكد من مراجعة عرض محتوى
مستودع التعليمات البرمجية المصدر الخاص بك لامتدادك (داخل دليل الامتداد)
يمكن لملفات POSTINSTALL الوصول إلى قيم المعلمات والعديد من المتغيرات المتعلقة بالوظيفة للامتداد. عندما يتم عرض محتوى POSTINSTALL في وحدة تحكم Firebase، يتم عرض القيم الفعلية بدلاً من المعلمة أو مراجع المتغير. تعرف على المزيد أدناه حول كيفية الإشارة إلى المعلمات والمتغيرات في ملف POSTINSTALL الخاص بك.
ما هي بعض أفضل الممارسات؟
- اجعل المحتوى الكامل لملف
POSTINSTALLموجزًا ولكن وصفيًا. - قم بتقسيم المحتوى باستخدام العناوين لفصل المهام أو المفاهيم المميزة.
- فكر في نشر تعليمات تفصيلية لسير عمل أو مهمة محددة على موقع الويب الخاص بك ( مثال ) أو في ملفات تخفيض السعر التكميلية داخل مستودع الامتدادات ( مثال ).
- المعلمات المرجعية والمتغيرات المتعلقة بالوظيفة بحيث يرى المستخدم القيم التي تم تكوينها في سياق التعليمات
المعلمات المرجعية والمتغيرات
بعد التثبيت، تعرض وحدة تحكم 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} | ||
| اسم الوظيفة المنشورة النهائية، والتي تتضمن معرف مثيل الملحق | الصيغة المعممة: قيمة المثال: | |
${function: function-name .url} (ينطبق فقط على وظائف HTTP) | ||
| عنوان URL للوظيفة النهائية المنشورة ، والتي يمكن لرمز العميل تقديم طلبات HTTP إليها | الصيغة المعممة: قيمة المثال: | |
نوصي باستخدام أكبر قدر ممكن من النص المعياري التالي، حسب ما ينطبق على ملحقك.
بالنسبة لجميع الإضافات، قم بتضمين القسم التالي لمساعدة المستخدمين في مراقبة الإضافات المثبتة لديهم:
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 جديد. يمكنك توجيه المستخدمين لديك لاختبار مثيل مثبت لامتدادك عن طريق إضافة مستخدم مصادقة جديد يدويًا في وحدة التحكم. ويمكنهم بعد ذلك مراقبة المستند الجديد الذي تم إنشاؤه في قسم Cloud Firestore بوحدة التحكم.
إضافة رمز من جانب العميل
عندما يكون ذلك ممكنًا، يمكنك أيضًا إرشاد المستخدمين حول كيفية إضافة تعليمات برمجية من جانب العميل لتشغيل الامتداد الخاص بك. يجب عليك توجيه المستخدمين إلى الوثائق الرسمية لواجهات برمجة التطبيقات التي سيحتاجون إلى استخدامها. يمكنك أيضًا تضمين نماذج تطبيقات أو نماذج عملاء مجمعة لمساعدة المستخدمين على دمج الامتداد في تطبيقاتهم (راجع ملحق العداد الموزع للحصول على مثال).
لكي يتمكن المستخدمون من تشغيل وظيفة يتم تشغيلها بواسطة طلب HTTP (وبالتالي الامتداد)، يتعين عليك تزويدهم باسم الوظيفة المنشورة أو عنوان URL الخاص بها.
اسم الوظيفة المنشورة النهائية ليس هو نفس name الذي حددته في كائن مورد الوظيفة داخل extension.yaml . لاستيعاب عمليات التثبيت المتعددة لنفس الامتداد في المشروع، يقوم Firebase بإعادة تسمية الوظيفة بهذا التنسيق:ext- extension-instance-id - function-name .
النقاط التالية عبارة عن نص نموذجي مقترح لتضمينه في ملف POSTINSTALL الخاص بامتدادك. بعد التثبيت، تعرض وحدة تحكم Firebase محتويات ملف POSTINSTALL وتملأ هذه المراجع بالقيم الفعلية التي تم تكوينها للمثيل المثبت. على سبيل المثال، إذا قمت بتعريف دالة باسم yourFunction ، فيمكنك تضمين ما يلي (حسب الاقتضاء):
بالنسبة لوظائف HTTP
onRequestTo 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.md الذي يوثق التغييرات المضمنة في كل إصدار جديد من ملحقك الذي تنشره. ضع كل إصدار تحت رأس المستوى الثاني ( ## ); بخلاف ذلك، يمكنك استخدام تنسيق 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 وCLI، عندما يقوم المستخدمون بالترقية إلى إصدارات جديدة من ملحقك. تعرض وحدة تحكم Firebase وCLI فقط التغييرات التي قد تدخل حيز التنفيذ إذا أكمل المستخدم الترقية.
- مستودع الكود المصدري لامتدادك (داخل دليل الامتداد).