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

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

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

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

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

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

כדי לגשת לערכים של פרמטרים שהוגדרו בקובץ POSTINSTALL, משתמשים בתחביר הבא: ${param:PARAMETER_NAME}

אפשר גם להפנות למשתנים הבאים שקשורים לפונקציה בקובץ POSTINSTALL בלבד. Firebase תומך במשתנים האלה כדי שתוכלו לספק למשתמשים הנחיות בקלות רבה יותר אחרי ההתקנה. אפשר להשתמש בהם רק בקובץ POSTINSTALL כי הערכים של המשתנים האלה זמינים רק אחרי ההתקנה.

בטבלה הזו, הערך של השדה name באובייקט המשאב של הפונקציה ב-extension.yaml הוא function-name.

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