פרסום התוסף

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

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

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

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

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

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

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

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

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

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

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

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.

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

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