هر برنامه افزودنی باید مستنداتی داشته باشد که به کاربران آموزش دهد که برنامه افزودنی چه کاری انجام می دهد و چگونه از آن استفاده کنند.
حداقل مستندات مورد نیاز این مجموعه از سه فایل علامت گذاری است:
-
PREINSTALL.md -
POSTINSTALL.md -
CHANGELOG.md
علاوه بر این، شما همچنین باید تولید را در نظر بگیرید:
- یک فایل
READMEبرای مخزن عمومی پسوند. - آموزش‌ها، راهنماها و مرجع طولانی‌تر در وب‌سایت خودتان منتشر شده و در
PREINSTALL.mdشما پیوند داده شده است.
برای یادگیری برخی از بهترین شیوه‌ها و عبارت‌ها و ساختار رایج، توصیه می‌کنیم فایل‌های موجود با پسوندهای رسمی Firebase را مرور کنید.
ایجاد یک README
فهرست برنامه افزودنی شما می تواند به صورت اختیاری حاوی یک 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قرار می گیرند) - شرح مختصری از هرگونه پیامدهای صورتحساب (با متن دیگ بخار شروع کنید)
این محتوا کجا به کاربر نمایش داده می شود؟
- در صفحه برنامه افزودنی در extensions.dev .
- مخزن کد منبع شما برای برنامه افزودنی شما (داخل فهرست برنامه افزودنی)
- به عنوان بخشی از README برنامه افزودنی (اگر از Firebase CLI استفاده می کنید
--markdown > README.md
فایل های PREINSTALL نمی توانند به مقادیر پارامتر برای برنامه افزودنی دسترسی پیدا کنند، بنابراین نباید انتظار داشته باشید که ارجاعات پارامتر با مقادیر واقعی ارائه شوند.
برخی از بهترین شیوه ها چیست؟
- در صورت امکان، محتوای کامل فایل
PREINSTALLرا زیر یک صفحه نگه دارید - سطح جزئیاتی را که کاربر نهایی باید قبل از نصب برنامه افزودنی بداند، ارائه دهید
- دستورالعمل های دقیق را در فایل
POSTINSTALLیا سایر فایل های تکمیلی قرار دهید - اگر ابزارها یا اسکریپت های دیگری را برای پشتیبانی از برنامه افزودنی ارائه می دهید، به طور خلاصه ذکر کنید
توصیه می‌کنیم تا حد امکان از متن دیگ بخار زیر استفاده کنید، تا آنجا که برای برنامه افزودنی شما قابل استفاده است. ما چند مثال ارائه کرده‌ایم، اما مهم‌ترین نکته این است که اطمینان حاصل شود که همه سرویس‌های صورتحساب Google و غیر 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
- دستورالعمل های مختصر برای نحوه نظارت بر افزونه نصب شده (شروع با متن boilerplate )
این محتوا کجا به کاربر نمایش داده می شود؟
در کنسول 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 انجام دهند، مخصوصاً برای آزمایش اولیه برنامه افزودنی شما. به عنوان مثال، فرض کنید برنامه افزودنی شما هر زمان که یک کاربر جدید Firebase Authentication ایجاد می شود، یک سند Cloud Firestore جدید ایجاد می کند. می توانید با افزودن دستی یک کاربر احراز هویت جدید در کنسول، به کاربران خود دستور دهید تا نمونه نصب شده برنامه افزودنی خود را آزمایش کنند. سپس می توانند سند جدید ایجاد شده در بخش Cloud Firestore کنسول را مشاهده کنند.
کد سمت مشتری را اضافه کنید
در صورت امکان، همچنین می‌توانید به کاربران خود آموزش دهید که چگونه کد سمت سرویس گیرنده را برای فعال کردن برنامه افزودنی خود اضافه کنند. شما باید کاربران را به اسناد رسمی برای APIهایی که باید استفاده کنند هدایت کنید. همچنین می‌توانید از برنامه‌های نمونه یا نمونه‌های مشتری کامپایل‌شده استفاده کنید تا به کاربران خود کمک کنید تا برنامه افزودنی را در برنامه خود ادغام کنند (برای مثال به افزونه Distributed Counter مراجعه کنید).
برای اینکه کاربران شما بتوانند یک تابع راه‌اندازی شده با درخواست 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
چه محتوایی در این فایل وجود دارد؟
هر برنامه افزودنی باید یک فایل 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 و CLI، هنگامی که کاربران به نسخه‌های جدید برنامه افزودنی شما ارتقا می‌دهند. کنسول Firebase و CLI فقط تغییراتی را نشان می‌دهند که در صورت تکمیل ارتقاء توسط کاربر اعمال می‌شوند.
- مخزن کد منبع برنامه افزودنی شما (داخل فهرست برنامه افزودنی).