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

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

התיעוד המינימלי שנדרש הוא קבוצה של שלושה קובצי 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 של התוסף (אם משתמשים בדגל Firebase CLI --markdown > README.md)

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

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

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