יצירת תיעוד למשתמשים עבור התוסף

לכל תוסף חייב להיות תיעוד שמסביר למשתמשים מה התוסף עושה ואיך להשתמש בו.

התיעוד המינימלי הנדרש הוא קבוצה של שלושה קובצי Markdown:

• PREINSTALL.md
• POSTINSTALL.md
• CHANGELOG.md

בנוסף, כדאי לשקול ליצור:

• קובץ README למאגר הציבורי של התוסף.
• מדריכים, חומרי עזר וסרטוני הדרכה ארוכים יותר שפורסמו באתר שלכם ונוסף אליהם קישור בPREINSTALL.md.

כדי ללמוד כמה שיטות מומלצות, ניסוחים נפוצים ומבנים, מומלץ לעיין בקבצים שזמינים עם התוספים הרשמיים של Firebase.

יצירת קובץ README

ספריית התוספים יכולה להכיל קובץ README. שימו לב שהפקודה firebase ext:dev:init לא יוצרת אותו בשבילכם באופן אוטומטי.

עם זאת, ה-CLI של 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)
• תיאור קצר של ההשלכות על החיוב (מתחילים עם טקסט סטנדרטי)

איפה התוכן הזה מוצג למשתמש?

מסוף Firebase">

התקנה מראש של תוכן במסוף Firebase

מסוף Firebase">

• בדף של התוסף ב-extensions.dev.
• מאגר קוד המקור של התוסף (בתוך ספריית התוסף)
• כחלק מקובץ ה-README של התוסף (אם משתמשים בדגל --markdown > README.md של ה-CLI של Firebase)

לקובצי PREINSTALL אין גישה לערכי הפרמטרים של התוסף, ולכן הפניות לפרמטרים לא יוצגו עם ערכים בפועל.

מהן השיטות המומלצות?

• אם אפשר, התוכן המלא של הקובץ PREINSTALL צריך להיות באורך של פחות מעמוד אחד.
• לספק את רמת הפירוט שמשתמש הקצה חייב לדעת לפני שהוא מתקין את התוסף.
• הוספת הוראות מפורטות בקובץ POSTINSTALL או בקבצים משלימים אחרים
• ציינו בקצרה אם אתם מספקים כלים או סקריפטים אחרים לתמיכה בתוסף.

טקסט סטנדרטי (בוילרפלייט) מועיל של PREINSTALL

מומלץ להשתמש בכמה שיותר מהטקסט הבא, בהתאם לתוסף שלכם. נתנו כמה דוגמאות, אבל הכי חשוב לוודא שכל השירותים שמחויבים על ידי Google ועל ידי גורמים אחרים מופיעים ברשימה.

אפשר להשתמש במקורות המידע הבאים כדי למצוא את פרטי התמחור הנכונים של המוצר:

• מחירון המוצרים של Google Cloud
• סקירה כללית של התמחור ב-Firebase

בכל התוספים, צריך לכלול את הקטע הזה כדי לעזור למשתמשים להבין את ההשלכות על החיוב:

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">

תוכן לאחר ההתקנה במסוף Firebase

מסוף Firebase">

• במסוף Firebase אחרי שמשתמש מתקין את התוסף (בכרטיס הפרטים של התוסף המותקן)

  • חשוב לבדוק איך התוכן של POSTINSTALL מוצג על ידי התקנת התוסף בפרויקט אמיתי.

• מאגר קוד המקור של התוסף (בתוך ספריית התוסף)

קובצי POSTINSTALL יכולים לגשת לערכי הפרמטרים ולכמה משתנים שקשורים לפונקציות של התוסף. כשתוכן POSTINSTALL מוצג במסוף Firebase, מוצגים הערכים בפועל ולא ההפניות לפרמטרים או למשתנים. בהמשך מוסבר איך להפנות לפרמטרים ולמשתנים בקובץ POSTINSTALL.

מהן השיטות המומלצות?

• התוכן המלא של הקובץ POSTINSTALL צריך להיות תמציתי אבל תיאורי.
• כדאי לחלק את התוכן באמצעות כותרות כדי להפריד בין משימות או מושגים שונים.
• כדאי לפרסם הוראות מפורטות לתהליך עבודה או למשימה ספציפיים באתר (דוגמה) או בקובצי Markdown נוספים במאגר של התוסף (דוגמה).
• פרמטרים של קובצי עזר ומשתנים שקשורים לפונקציות, כדי שהמשתמש יראה את הערכים שהוגדרו בהקשר של ההוראות

הפניה לפרמטרים ולמשתנים

אחרי ההתקנה, במסוף Firebase מוצג התוכן של קובץ ה-POSTINSTALL של התוסף. אם אתם מפנים לפרמטרים ולמשתנים שקשורים לפונקציות (ראו את הטבלה בהמשך) בקובץ POSTINSTALL, המסוף מאכלס את ההפניות האלה בערכים בפועל של המכונה המותקנת.

טיפ: אם הערכים יכולים להיות ארוכים (כמו נתיב של מסד נתונים או כתובת URL של פונקציה), כדאי להפנות לפרמטר או למשתנה בסוף המשפטים והקטעים. השיטה המומלצת הזו מקלה על קריאת המשפטים במסוף Firebase כשתוכן הקובץ 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

טקסט סטנדרטי (בוילרפלייט) מועיל של POSTINSTALL

מומלץ להשתמש בכמה שיותר מהטקסט הבא, בהתאם לתוסף שלכם.

בכל התוספים, צריך לכלול את הקטע הבא כדי לעזור למשתמשים לעקוב אחרי התוסף שהם התקינו:

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 חדש. אתם יכולים להורות למשתמשים לבדוק מופע מותקן של התוסף על ידי הוספה ידנית של משתמש Authentication חדש במסוף. הם יכולים לראות את המסמך החדש שנוצר בקטע Cloud Firestore במסוף.

הוספת קוד בצד הלקוח

במקרים הרלוונטיים, אתם יכולים גם להנחות את המשתמשים איך להוסיף קוד בצד הלקוח כדי להפעיל את התוסף. אתם צריכים להפנות את המשתמשים למסמכי התיעוד הרשמיים של ממשקי ה-API שהם צריכים להשתמש בהם. אתם יכולים גם לכלול אפליקציות לדוגמה או דוגמאות ללקוחות מקומפלים כדי לעזור למשתמשים לשלב את התוסף באפליקציה שלהם (לדוגמה, עיינו בתוסף Distributed Counter).

תוספים שמופעלים על ידי בקשת HTTP

כדי שהמשתמשים יוכלו להפעיל פונקציה שמופעלת באמצעות בקשת HTTP (וכך גם את התוסף), צריך לספק להם את השם או את כתובת ה-URL של הפונקציה שנפרסה.

השם של הפונקציה שנפרסה בסופו של דבר לא זהה ל-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}`**.
  

חשוב: כדי שהמשתמשים יוכלו להשתמש בתוסף שמופעל על ידי בקשת HTTP, הם צריכים להגדיר את הפונקציות שנפרסו לתוסף כנגישות באופן ציבורי. ההוראות המפורטות שצריך לספק למשתמשים מופיעות בדוגמאות לטקסטים סטנדרטיים שלמעלה.

כתיבת קובץ 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 מוצגים רק השינויים שייכנסו לתוקף אם המשתמש ישלים את השדרוג.
• מאגר קוד המקור של התוסף (בתוך ספריית התוסף).