פרסום התוסף

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    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 ב-CLI של Firebase:

    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 ב-CLI של Firebase, ומציינים את stable בתור שלב הפרסום:

    firebase ext:dev:upload your_publisher_id/your_extension_id

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

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

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

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

  • בדקתם באופן יסודי את התוסף ואת תהליך ההתקנה.
  • המסמכים מלאים ונכונים, והם מוצגים היטב במסוף Firebase.
  • השם והמיתוג של בעל התוכן הדיגיטלי מזהים אתכם באופן ברור ומדויק כבעלי התוכן הדיגיטלי.
  • השם, התיאור והסמל של התוסף מייצגים בבירור ובאופן מדויק את המטרה של התוסף.
  • הוספת תגים מועילים ומדויקים.
  • הצהרת ב-extension.yaml על כל ממשקי ה-API של Google ושאינם של 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. לוחצים על Deprecate version.

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.*

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

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

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

firebase ext:dev:undeprecate your_publisher_id/your_extension_id versions

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

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

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

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

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

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

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

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

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

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