هر افزونه‌ای باید مستنداتی داشته باشد که به کاربران نحوه‌ی استفاده از آن و عملکرد افزونه را آموزش دهد.
حداقل مستندات مورد نیاز، این مجموعه از سه فایل 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-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 نمای کلی افزونه شماست، نوعی صفحه «بازاریابی».
چه محتوایی در این فایل وجود دارد؟
- شرح جامعی از عملکرد افزونه شما
- فهرست پیش‌نیازها، مانند راه‌اندازی پایگاه داده یا دسترسی به یک سرویس غیر گوگل ( مثال )
- شرح مختصری از هرگونه کار قبل از نصب و دستورالعمل‌های آنها
- شرح مختصری از هرگونه وظیفه پس از نصب ( مثال ) (دستورالعمل‌های دقیق در
POSTINSTALLقرار دارند) - شرح مختصری از هرگونه پیامد صورتحساب (با متن تکراری شروع کنید)
این محتوا کجا به کاربر نمایش داده می‌شود؟
کنسول فایربیس">
کنسول فایربیس">
- در صفحه افزونه در extensions.dev .
- مخزن کد منبع شما برای افزونه‌تان (داخل دایرکتوری افزونه)
- به عنوان بخشی از README افزونه (اگر از Firebase CLI استفاده می‌کنید)
--markdown > README.mdflag
فایل‌های PREINSTALL نمی‌توانند به مقادیر پارامتر برای افزونه دسترسی داشته باشند، بنابراین نباید انتظار داشته باشید که ارجاعات پارامتر با مقادیر واقعی رندر شوند.
برخی از بهترین شیوه‌ها کدامند؟
- در صورت امکان، کل محتوای فایل
PREINSTALLرا در کمتر از یک صفحه نگه دارید. - سطحی از جزئیات را ارائه دهید که یک کاربر نهایی قبل از نصب افزونه کاملاً باید بداند.
- دستورالعمل‌های دقیق را در فایل
POSTINSTALLیا سایر فایل‌های تکمیلی قرار دهید. - اگر ابزارها یا اسکریپت‌های دیگری برای پشتیبانی از افزونه ارائه می‌دهید، به طور خلاصه ذکر کنید
توصیه می‌کنیم تا حد امکان از متن‌های تکراری زیر، تا جایی که برای افزونه شما مناسب است، استفاده کنید. ما چند مثال ارائه داده‌ایم، اما مهمترین نکته این است که مطمئن شوید همه سرویس‌های گوگل و غیر گوگل که هزینه آنها پرداخت می‌شود، فهرست شده‌اند.
برای اطلاع از قیمت دقیق محصولات می‌توانید از منابع زیر استفاده کنید:
برای همه افزونه‌ها، این بخش را اضافه کنید تا به کاربرانتان در درک مفاهیم صورتحساب کمک کنید:
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 خود ارجاع دهید. فایربیس از این متغیرها پشتیبانی می‌کند تا بتوانید پس از نصب، راهنمایی‌های لازم را به کاربران خود ارائه دهید. استفاده از آنها فقط در فایل 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 جدید ایجاد می‌کند. می‌توانید با اضافه کردن دستی یک کاربر Authentication جدید در کنسول، به کاربران خود دستور دهید که یک نمونه نصب شده از افزونه شما را آزمایش کنند. سپس آنها می‌توانند سند جدید ایجاد شده در بخش 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}`**.
نوشتن یک فایل CHANGELLOG
چه محتوایی در این فایل وجود دارد؟
هر افزونه باید یک فایل 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 ، وقتی کاربران به نسخه‌های جدید افزونه شما ارتقا می‌یابند، کنسول و رابط Firebase فقط تغییراتی را نمایش می‌دهند که در صورت تکمیل ارتقا توسط کاربر اعمال می‌شوند.
- مخزن کد منبع افزونه شما (داخل دایرکتوری افزونه).