פרסום התוסף

בדף הזה מוסבר איך לפרסם תוסף במרכז התוספים.

לפני שמתחילים

כדי לפרסם תוסף, קודם צריך להירשם כמפרסם תוספים.

מקורות שניתנים לאימות

לכל התוספים שמתפרסמים ב-Extensions Hub חייב להיות מקור שניתן לאימות באופן ציבורי. במקום להעלות את קוד המקור של התוסף ישירות אל מרכז התוספים, מציינים את מיקום המקור ומרכז התוספים יוריד אותו ויבנה אותו משם.

בשלב הזה, המשמעות היא שקוד המקור של התוסף צריך להיות זמין במאגר ציבורי ב-GitHub.

להעלאה ממקור שאפשר לאמת יש כמה יתרונות:

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

מחזור פיתוח מומלץ

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

היכולת הזו מאפשרת מחזור פיתוח כמו זה שמתואר כאן:

1. מפתחים את התוסף ומשפרים אותו במהירות באמצעות חבילת כלי האמולטור של Firebase.

2. כדי לבדוק את התוסף בפרויקט אמיתי, מתקינים אותו ממקור מקומי:

   firebase ext:install /path/to/extension
   firebase deploy --only extensions

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

4. מעלים את הגרסה הסופית והיציבה למרכז התוספים (הוראות בהמשך) ושולחים אותה לבדיקה. אם התוסף יעבור את הבדיקה, הוא יפורסם במרכז התוספים.

5. מגדילים את מספר הגרסה ב-extension.yaml וחוזרים על התהליך הזה עבור הגרסה הבאה של התוסף.

העלאת תוסף חדש

כדי להעלות תוסף בפעם הראשונה:

1. אופציונלי: שומרים את הקוד במאגר ציבורי ב-GitHub.

2. מריצים את הפקודה ext:dev:upload של Firebase CLI:

   GitHub

   firebase ext:dev:upload your_publisher_id/your_extension_id

   מקור מקומי

   cd /path/to/extension
   firebase ext:dev:upload your_publisher_id/your_extension_id --local

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

   • מזהה בעל האתר שרשמתם.

   • מחרוזת מזהה שתשמש לזיהוי התוסף. נותנים לתוספים שם בפורמט הבא: firebase-product-description-of-tasks-performed. לדוגמה: firestore-bigquery-export

   הפקודה תבקש מכם מידע נוסף:

   • אם אתם מעלים מ-GitHub:

     • כתובת ה-URL למאגר של התוסף ב-GitHub. שימו לב: מאגר יכול להכיל כמה תוספים, כל עוד לכל תוסף יש שורש ייחודי.

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

     • הספרייה במאגר שמכילה את התוסף.

     • ההפניה ב-Git לקומיט שממנו רוצים ליצור את קוד המקור של גרסת התוסף. זה יכול להיות גיבוב של קומיט, תג או שם של ענף.

   • שלב הפרסום של הגרסה שאתם מעלים.

     השלבים alpha, beta ו-rc (גרסה מועמדת להפצה) מיועדים להעלאת גרסאות לפני ההפצה להתקנה על ידי בודקים. אפשר להשתמש באחד מהשלבים האלה כדי להעלות תוסף חדש בפעם הראשונה.

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

   שימו לב שלא מציינים מספר גרסה – הערך הזה מגיע מקובץ extension.yaml. כשמעלים גרסת טרום-השקה של תוסף, השלב ומספר ההעלאה מצורפים לגרסה. לדוגמה, אם הערך של extension.yaml הוא 1.0.1 ואתם מעלים גרסת קנדידט, הגרסה שתתקבל היא 1.0.1-rc.0. אם תעלו גרסת קנדידט נוספת של אותה גרסה, המספר יגדל אוטומטית ותתקבל הגרסה 1.0.1-rc.1, וכן הלאה.

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

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

  https://console.firebase.google.com/project/_/extensions/install?ref=your_publisher_id/your_extension_id@version

  אפשר לשתף את הקישור הישיר עם הבודקים.

• באמצעות ה-CLI: משתמשים יכולים להתקין את התוסף על ידי העברת מחרוזת מזהה התוסף לפקודה ext:install:

  firebase ext:install your_publisher_id/your_extension_id@version \
      --project=destination_project_id
  

העלאה של גרסה מעודכנת

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

כדי להעלות עדכון:

1. אופציונלי: שומרים את הקוד במאגר Git ציבורי.

2. מריצים את הפקודה ext:dev:upload של Firebase CLI:

   GitHub

   firebase ext:dev:upload your_publisher_id/your_extension_id

   הפעם לא תתבקשו לציין את מאגר GitHub או את ספריית הבסיס של התוסף, כי הם כבר הוגדרו עבור התוסף. אם ביצעתם רפקטורינג של מבנה המאגר או העברתם אותו למאגר חדש, אתם יכולים לשנות את המאגרים באמצעות ארגומנטי הפקודה --root ו---repo.

   מקור מקומי

   cd /path/to/extension
   firebase ext:dev:upload your_publisher_id/your_extension_id --local

שליחת תוסף לפרסום

כשמוכנים לפרסם את התוסף לציבור:

1. שמירת הקוד במאגר Git ציבורי. (חובה בגרסאות ציבוריות).

2. מריצים את הפקודה ext:dev:upload של Firebase CLI ומציינים את stable כשלב ההפצה:

   firebase ext:dev:upload your_publisher_id/your_extension_id

3. אם פרסמתם בעבר גרסה של התוסף, העלאה של גרסה יציבה חדשה תשלח אוטומטית את התוסף לבדיקה.

   אם העליתם את הגרסה היציבה הראשונה של התוסף, אתם יכולים למצוא את התוסף במרכז הבקרה לבעלי תוכן דיגיטלי וללחוץ על פרסום ב-Extensions Hub.

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

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

• בדקתם היטב את התוסף ואת תהליך ההתקנה.
• התיעוד שלכם מלא ונכון, והוא מוצג בצורה טובה במסוף Firebase.
• השם והמיתוג של בעל האתר מזהים אתכם בבירור ובאופן מדויק כבעלי האתר.
• השם, התיאור והסמל של התוסף מייצגים באופן ברור ומדויק את המטרה של התוסף.
• השתמשת בתגים מועילים ומדויקים.
• הצהרת ב-extension.yaml על כל ממשקי ה-API של Google ושל צד שלישי שבהם נעשה שימוש, ועל כל סוגי האירועים שהתוסף שולח.
• אתם מבקשים גישה רק לתפקידים שנדרשים כדי שהתוסף יפעל, והסברתם למשתמשים בצורה ברורה למה אתם צריכים גישה כזו.
• קובצי המקור שלך מורשים בבירור בהתאם לתנאים של Apache-2.0.

ניהול תוספים שהועלו ופורסמו

הצגת רשימה של התוספים שהועלו

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

לוח הבקרה של בעל התוכן הדיגיטלי

אפשר לראות אותם במרכז הבקרה של בעל התוכן הדיגיטלי.

Firebase CLI

מריצים את הפקודה ext:dev:list:

firebase ext:dev:list your_publisher_id

הצגת השימוש בתוספים שהועלו

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

לוח הבקרה של בעל התוכן הדיגיטלי

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

Firebase CLI

מריצים את הפקודה ext:dev:usage:

firebase ext:dev:usage your_publisher_id

הוצאה משימוש של גרסה של תוסף

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

כדי להוציא משימוש גרסה של תוסף, מבצעים אחת מהפעולות הבאות:

לוח הבקרה של בעל התוכן הדיגיטלי

1. במרכז הבקרה של בעל התוכן הדיגיטלי, לוחצים על התוסף כדי לפתוח את תצוגת הפרטים שלו.
2. בוחרים את הגרסה שרוצים להוציא משימוש.
3. לוחצים על הוצאת גרסה משימוש.

Firebase CLI

מריצים את הפקודה ext:dev:deprecate:

firebase ext:dev:deprecate your_publisher_id/your_extension_id versions \
    [--message "deprecation_message"]

אפשר לציין גרסה אחת או טווח גרסאות. דוגמאות:

• 1.0.2
• 1.1.0-1.1.7
• <1.2.0
• 1.1.*

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

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

כדי לבטל הוצאה משימוש, משתמשים במרכז השליטה של בעלי האפליקציות או מריצים את הפקודה ext:dev:undeprecate של Firebase CLI:

firebase ext:dev:undeprecate your_publisher_id/your_extension_id versions

נספח: פתרון בעיות שגיאה ב-build

כשמעלים את התוסף, קוד המקור עובר קודם הידור (build) בשרת העורפי בתהליך הבא:

1. משכפל את המאגר שלכם ב-GitHub ומבצע checkout של הפניה למקור שצוינה.

2. הפקודה מתקינה תלות ב-NPM על ידי הרצת npm clean-install בכל ספריית מקור של פונקציה שצוינה ב-extension.yaml (ראו sourceDirectory במשאבים של Cloud Functions).

   שימו לב לנקודות הבאות:

   • לכל קובץ package.json צריך להיות קובץ package-lock.json תואם. מידע נוסף זמין במאמר npm-ci.

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

3. הקוד נבנה על ידי הפעלת npm run build בכל ספריית מקור של פונקציה שצוינה ב-extension.yaml.

רק ספריית הבסיס של התוסף תישמר בחבילת התוסף הסופית שתשותף.

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