לכל תוסף חייב להיות תיעוד שמלמד את המשתמשים מה התוסף עושה וכיצד להשתמש בו.
התיעוד המינימלי, הנדרש, הוא קבוצה זו של שלושה קובצי סימון:
-
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 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
) - תיאור קצר של השלכות חיוב כלשהן (התחל עם הטקסט של הלוח )
היכן מוצג תוכן זה למשתמש?
- בעמוד התוסף ב- extensions.dev .
- מאגר קוד המקור שלך עבור התוסף שלך (בתוך ספריית ההרחבות)
- כחלק מה-README של התוסף (אם אתה משתמש ב-Firebase CLI
)--markdown > README.md
קבצי PREINSTALL
אינם יכולים לגשת לערכי הפרמטרים של התוסף, לכן אין לצפות שהפניות לפרמטרים יוצגו עם ערכים בפועל.
מהן כמה שיטות עבודה מומלצות?
- שמור את התוכן המלא של קובץ ה-
PREINSTALL
מתחת לדף אחד , אם אפשר - ספק את רמת הפירוט שמשתמש קצה צריך לדעת לפני התקנת התוסף
- שים הוראות מפורטות בקובץ
POSTINSTALL
או בקבצים משלימים אחרים - ציין בקצרה אם אתה מספק כלים או סקריפטים אחרים לתמיכה בהרחבה
אנו ממליצים להשתמש בכמה שיותר מטקסט ה-boilerplate הבא, בהתאם להתאמה עבור ההרחבה שלך. סיפקנו כמה דוגמאות, אבל הנקודה החשובה ביותר היא לוודא שכל השירותים החיוביים של 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
- הנחיות קצרות כיצד לנטר את התוסף המותקן (התחל עם טקסט הלוח )
היכן מוצג תוכן זה למשתמש?
במסוף 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) | ||
כתובת האתר של הפונקציה הסופית שנפרסה , שאליה קוד הלקוח יכול לבצע בקשות HTTP | פורמט כללי: ערך לדוגמה: |
אנו ממליצים להשתמש בכמה שיותר מטקסט ה-boilerplate הבא, בהתאם להתאמה עבור ההרחבה שלך.
עבור כל התוספים, כלול את הסעיף הבא כדי לעזור למשתמשים שלך לעקוב אחר התוסף המותקן שלהם:
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 של המסוף.
הוסף קוד בצד הלקוח
כאשר רלוונטי, תוכל גם להדריך את המשתמשים שלך כיצד להוסיף קוד בצד הלקוח כדי להפעיל את התוסף שלך. עליך להפנות את המשתמשים לתיעוד הרשמי של ממשקי ה-API שהם יצטרכו להשתמש בהם. אתה יכול גם לכלול אפליקציות לדוגמה או דוגמאות של לקוחות כדי לעזור למשתמשים שלך לשלב את התוסף באפליקציה שלהם (עיין בתוסף ה- Distributed Counter לדוגמא).
כדי שהמשתמשים שלך יוכלו להפעיל פונקציה המופעלת בבקשת HTTP (ולפיכך את התוסף), עליך לספק להם את שם הפונקציה שנפרסה או כתובת האתר שלה.
השם של הפונקציה הפרוסה הסופית אינו זהה 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}`**.
כתיבת קובץ 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 מציגים רק את השינויים שייכנסו לתוקף אם המשתמש היה משלים את השדרוג.
- מאגר קוד המקור של התוסף שלך (בתוך ספריית ההרחבות).