מניפסטים של תוספים ל-Google Workspace

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

במסמכי התיעוד האלה מוסבר בפירוט איך להגדיר קובץ מניפסט לתוסף ל-Google Workspace.

מבנה קובץ המניפסט של תוספים ל-Google Workspace

תוספים ל-Google Workspace משתמשים בקובץ המניפסט כדי להגדיר כמה היבטים של המראה וההתנהגות.

מאפייני המניפסט של תוספים ל-Google Workspace מאורגנים בקטע addOns.

מידע על קובצי מניפסט של Google Apps Script זמין במאמר בנושא מבנה המניפסט.
מידע על קובצי מניפסט לתוספים שנבנו עם נקודות קצה של HTTP זמין במאמר projects.deployments.

קבצים מסוג Manifest ל-Google Chat

אם התוסף שלכם ל-Google Workspace מרחיב את Google Chat, אתם צריכים להגדיר אפליקציית Chat ל-Google Chat על ידי הפעלה והגדרה של Google Chat API במסוף Google Cloud.

הגדרות נפוצות של קובץ המניפסט (כולל addons.common) מוזנחות ב-Chat. אפשר להשתמש ב-Chat API כדי להגדיר את ההגדרות הבאות של Chat:

השם, הלוגו והתיאור של אפליקציית Chat בממשק המשתמש של Chat.
טריגרים של אפליקציות ל-Chat.

אם יצרתם את התוסף ב-Apps Script, מוסיפים או מעדכנים את האובייקטים הבאים במניפסט:

‫addons.chat (חובה)
‫oauthScopes (חובה אם אפליקציית Google Chat שלכם משתמשת ב-OAuth)

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

דוגמה להגדרת קובץ מניפסט של תוסף ל-Google Workspace

בדוגמאות הבאות מוצג החלק במניפסט שמגדיר תוסף ל-Google Workspace, כולל ההיבטים הבאים:

‫addOns.common מגדיר את השם, הלוגו, הצבעים והגדרות כלליות אחרות של התוסף.
קובץ המניפסט מגדיר דף בית משותף, אבל הוא גם מגדיר דפי בית ספציפיים ליומן Google, ל-Google Drive, ל-Google Docs, ל-Google Sheets ול-Google Slides. ‫Gmail משתמש בדף הבית שמוגדר כברירת מחדל.
הגדרות קובץ המניפסט לדוגמה מאפשרות את הפעולות הבאות:
- טריגרים של יומן eventOpen ושל eventUpdated.
- (Apps Script בלבד) שני פתרונות לשיחות ועידה ביומן.
- שתי פעולות אוניברסליות.
- ‫Drive onItemsSelectedTrigger.
- פעולת כתיבה ב-Gmail וטריגר הקשרי.
- אובייקט linkPreviewTriggers ב-Docs. תצוגה מקדימה של קישורים באמצעות צ'יפים חכמים
- אובייקט createActionTriggers ב-Docs. איך יוצרים משאבים של צד שלישי באמצעות התפריט '@'
- ממשקים ספציפיים לקבצים ב-Docs,‏ Sheets ו-Slides.
- אפשרות ל-Google Meet sidePanelUri ו-addOnOrigins.
- ‫(HTTP בלבד) שני HttpOptions לשליחת כותרת הרשאה ולתמיכה בהבעת הסכמה פרטנית.
בשדה oauthScopes מוגדרים היקפי ההרשאות של הפרויקט.
(Apps Script בלבד) התג urlFetchWhitelist מוודא שנקודות הקצה שאוחזרו תואמות לקידומות של כתובות URL מסוג HTTPS שצוינו. איך מוסיפים כתובות אתרים לרשימת ההיתרים

הקישורים בדוגמאות מפנים לתיאורי שדות בהפניה למניפסט של תוספים ל-Google Workspace ב-Apps Script וב-HTTP.

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

Apps Script

{
  "addOns": {
    "calendar": {
      "createSettingsUrlFunction": "getConferenceSettingsPageUrl",
      "conferenceSolution": [{
        "id": "my-video-conf",
        "logoUrl": "https://lh3.googleusercontent.com/...",
        "name": "My Video Conference",
        "onCreateFunction": "onCreateMyVideoConference"
      }, {
        "id": "my-streamed-conf",
        "logoUrl": "https://lh3.googleusercontent.com/...",
        "name": "My Streamed Conference",
        "onCreateFunction": "onCreateMyStreamedConference"
      }],
      "currentEventAccess": "READ_WRITE",
      "eventOpenTrigger": {
        "runFunction": "onCalendarEventOpen"
      },
      "eventUpdateTrigger": {
        "runFunction": "onCalendarEventUpdate"
      },
      "eventAttachmentTrigger": {
        "label": "My Event Attachment",
        "runFunction": "onCalendarEventAddAttachment"
      },
      "homepageTrigger": {
        "runFunction": "onCalendarHomePageOpen",
        "enabled": true
      }
    },
    "common": {
      "homepageTrigger": {
        "runFunction": "onDefaultHomePageOpen",
        "enabled": true
      },
      "layoutProperties": {
        "primaryColor": "#ff392b",
        "secondaryColor": "#d68617"
      },
      "logoUrl": "https://ssl.gstatic.com/docs/script/images/logo/script-64.png",
      "name": "Demo Google Workspace add-on",
      "openLinkUrlPrefixes": [
        "https://mail.google.com/",
        "https://script.google.com/a/google.com/d/",
        "https://drive.google.com/a/google.com/file/d/",
        "https://www.example.com/"
      ],
      "universalActions": [{
        "label": "Open settings",
        "runFunction": "getSettingsCard"
      }, {
        "label": "Open Help URL",
        "openLink": "https://www.example.com/help"
      }],
      "useLocaleFromApp": true
    },
    "drive": {
      "homepageTrigger": {
        "runFunction": "onDriveHomePageOpen",
        "enabled": true
      },
      "onItemsSelectedTrigger": {
        "runFunction": "onDriveItemsSelected"
      }
    },
    "gmail": {
      "composeTrigger": {
        "selectActions": [
          {
            "text": "Add images to email",
            "runFunction": "getInsertImageComposeCards"
          }
        ],
        "draftAccess": "METADATA"
      },
      "contextualTriggers": [
        {
          "unconditional": {},
          "onTriggerFunction": "onGmailMessageOpen"
        }
      ]
    },
    "docs": {
      "homepageTrigger": {
        "runFunction": "onEditorsHomepage"
      },
      "onFileScopeGrantedTrigger": {
        "runFunction": "onFileScopeGrantedEditors"
      },
      "linkPreviewTriggers": [
        {
        "runFunction": "onLinkPreview",
        "patterns": [
            {
              "hostPattern": "example.com",
              "pathPrefix": "example-path"
            }
        ],
        "labelText": "Link preview",
        "localizedLabelText": {
          "es": "Link preview localized in Spanish"
        },
        "logoUrl": "https://www.example.com/images/smart-chip-icon.png"
        }
      ],
      "createActionTriggers": [
        {
          "id": "exampleId",
          "labelText": "Example label text",
          "localizedLabelText": {
            "es": "Label text localized in Spanish"
          },
          "runFunction": "exampleFunction",
          "logoUrl": "https://www.example.com/images/case.png"
        }
      ]
    },
    "sheets": {
      "homepageTrigger": {
        "runFunction": "onEditorsHomepage"
      },
      "onFileScopeGrantedTrigger": {
        "runFunction": "onFileScopeGrantedEditors"
      }
    },
    "slides": {
      "homepageTrigger": {
        "runFunction": "onEditorsHomepage"
      },
      "onFileScopeGrantedTrigger": {
        "runFunction": "onFileScopeGrantedEditors"
      }
    },
    "meet": {
      "homepageTrigger",
      "Web": [
        {
          "sidePanelUrl": "https://myownpersonaldomain.com/sidePanelUrl",
          "supportsScreenSharing": true,
          "addOnOrigins": [
            "https://www.myownpersonaldomain.com",
            "https://www.myownpersonaldomain.com:443"
          ],
          "logoUrl": "https://myownpersonaldomain.com/logoUrl",
          "darkModeLogoUrl": "https://myownpersonaldomain.com/darkModeLogoUrl"
        }
    },
  },
  "oauthScopes": [
    "https://www.googleapis.com/auth/calendar.addons.execute",
    "https://www.googleapis.com/auth/calendar.addons.current.event.read",
    "https://www.googleapis.com/auth/calendar.addons.current.event.write",
    "https://www.googleapis.com/auth/drive.addons.metadata.readonly",
    "https://www.googleapis.com/auth/gmail.addons.current.action.compose",
    "https://www.googleapis.com/auth/gmail.addons.current.message.metadata",
    "https://www.googleapis.com/auth/userinfo.email",
    "https://www.googleapis.com/auth/script.external_request",
    "https://www.googleapis.com/auth/script.locale",
    "https://www.googleapis.com/auth/script.scriptapp",
    "https://www.googleapis.com/auth/drive.file",
    "https://www.googleapis.com/auth/documents.currentonly",
    "https://www.googleapis.com/auth/spreadsheets.currentonly",
    "https://www.googleapis.com/auth/presentations.currentonly",
    "https://www.googleapis.com/auth/workspace.linkpreview"
  ],
  "urlFetchWhitelist": [
    "https://www.example.com/myendpoint/"
  ]
}

HTTP

{
  "addOns": {
    "calendar": {
      "currentEventAccess": "READ_WRITE",
      "eventOpenTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onCalendarEventOpen"
      },
      "eventUpdateTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onCalendarEventUpdate"
      },
      "eventAttachmentTrigger": {
        "label": "My Event Attachment",
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onCalendarEventAddAttachment"
      },
      "homepageTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onCalendarHomePageOpen",
        "enabled": true
      }
    },
    "common": {
      "homepageTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onDefaultHomePageOpen",
        "enabled": true
      },
      "layoutProperties": {
        "primaryColor": "#ff392b",
        "secondaryColor": "#d68617"
      },
      "logoUrl": "https://ssl.gstatic.com/docs/script/images/logo/script-64.png",
      "name": "Demo Google Workspace add-on",
      "openLinkUrlPrefixes": [
        "https://mail.google.com/",
        "https://script.google.com/a/google.com/d/",
        "https://drive.google.com/a/google.com/file/d/",
        "https://www.example.com/"
      ],
      "universalActions": [{
        "label": "Open settings",
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=getSettingsCard"
      }, {
        "label": "Open Help URL",
        "openLink": "https://www.example.com/help"
      }],
      "useLocaleFromApp": true
    },
    "drive": {
      "homepageTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onDriveHomePageOpen",
        "enabled": true
      },
      "onItemsSelectedTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onDriveItemsSelected"
      }
    },
    "gmail": {
      "composeTrigger": {
        "actions": [
          {
            "label": "Add images to email",
            "runFunction": "https://myownpersonaldomain.com/mypage?trigger=getInsertImageComposeCards"
          }
        ],
        "draftAccess": "METADATA"
      },
      "contextualTriggers": [
        {
          "unconditional": {},
          "onTriggerFunction": "https://myownpersonaldomain.com/mypage?trigger=onGmailMessageOpen"
        }
      ]
    },
    "docs": {
      "homepageTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onEditorsHomepage"
      },
      "onFileScopeGrantedTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onFileScopeGrantedEditors"
      },
      "linkPreviewTriggers": [
        {
          "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onLinkPreview",
          "patterns": [
              {
                "hostPattern": "example.com",
                "pathPrefix": "example-path"
              }
          ],
          "labelText": "Link preview",
          "localizedLabelText": {
            "es": "Link preview localized in Spanish"
          },
          "logoUrl": "https://www.example.com/images/smart-chip-icon.png"
        }
      ],
      "createActionTriggers": [
        {
          "id": "exampleId",
          "labelText": "Example label text",
          "localizedLabelText": {
            "es": "Label text localized in Spanish"
          },
          "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onCreateAction",
          "logoUrl": "https://www.example.com/images/case.png"
        }
      ]
    },
    "sheets": {
      "homepageTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onEditorsHomepage"
      },
      "onFileScopeGrantedTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onFileScopeGrantedEditors"
      }
    },
    "slides": {
      "homepageTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onEditorsHomepage"
      },
      "onFileScopeGrantedTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onFileScopeGrantedEditors"
      }
    },
    "meet": {
      "homepageTrigger",
      "Web": [
        {
          "sidePanelUrl": "https://myownpersonaldomain.com/sidePanelUrl",
          "supportsScreenSharing": true,
          "addOnOrigins": [
            "https://www.myownpersonaldomain.com",
            "https://www.myownpersonaldomain.com:443"
          ],
          "logoUrl": "https://myownpersonaldomain.com/meetWebLogoUrl",
          "darkModeLogoUrl": "https://myownpersonaldomain.com/darkModeLogoUrl"
        }
      ]
    },
    "httpOptions": {
      "authorizationHeader": "SYSTEM_ID_TOKEN",
      "granularOauthPermissionSupport": "OPT_IN"
    }
  },
  "oauthScopes": [
    "https://www.googleapis.com/auth/calendar.addons.execute",
    "https://www.googleapis.com/auth/calendar.addons.current.event.read",
    "https://www.googleapis.com/auth/calendar.addons.current.event.write",
    "https://www.googleapis.com/auth/drive.addons.metadata.readonly",
    "https://www.googleapis.com/auth/gmail.addons.current.action.compose",
    "https://www.googleapis.com/auth/gmail.addons.current.message.metadata",
    "https://www.googleapis.com/auth/userinfo.email",
    "https://www.googleapis.com/auth/script.external_request",
    "https://www.googleapis.com/auth/script.locale",
    "https://www.googleapis.com/auth/script.scriptapp",
    "https://www.googleapis.com/auth/drive.file",
    "https://www.googleapis.com/auth/documents.currentonly",
    "https://www.googleapis.com/auth/spreadsheets.currentonly",
    "https://www.googleapis.com/auth/presentations.currentonly",
    "https://www.googleapis.com/auth/workspace.linkpreview"
  ]
}

כתובות URL ברשימת ההיתרים

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

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

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

שליפה או אחזור של מידע ממיקום חיצוני (כמו נקודות קצה של HTTPS) באמצעות שירות UrlFetch של Apps Script. כדי להוסיף כתובות URL לרשימת ההיתרים לצורך אחזור, צריך לכלול את השדה urlFetchWhitelist בקובץ המניפסט.
פותח או מציג כתובת URL בתגובה לפעולת משתמש (חובה לתוספי Google Workspace שפותחים או מציגים כתובות URL חיצוניות ל-Google). כדי להוסיף כתובות URL לרשימת ההיתרים לפתיחה, צריך לכלול את השדה addOns.common.openLinkUrlPrefixes בקובץ המניפסט.

הוספת קידומות לרשימת ההיתרים

כשמציינים רשימות היתרים בקובץ המניפסט (על ידי הכללה של השדה addOns.common.openLinkUrlPrefixes או urlFetchWhitelist), צריך לכלול רשימה של קידומות של כתובות URL. הקידומות שמוסיפים למניפסט צריכות לעמוד בדרישות הבאות:

כל קידומת חייבת להיות כתובת URL תקינה.
כל קידומת חייבת להשתמש ב-https:// ולא ב-http://.
לכל קידומת צריך להיות דומיין מלא.
לכל קידומת צריך להיות נתיב לא ריק. לדוגמה, https://www.google.com/ הוא ערך תקין, אבל https://www.google.com לא.
אפשר להשתמש בתווים כלליים לחיפוש כדי להתאים קידומות של תת-דומיין של כתובת URL.
אפשר להשתמש בתו כללי לחיפוש * בשדה addOns.common.openLinkUrlPrefixes כדי להתאים לכל הקישורים, אבל לא מומלץ לעשות זאת כי זה עלול לחשוף את נתוני המשתמש לסיכון ולהאריך את תהליך בדיקת התוסף. כדאי להשתמש בתו כללי רק אם הפונקציונליות של התוסף דורשת זאת.

כשקובעים אם כתובת URL תואמת לתחילית ברשימת ההיתרים, הכללים הבאים חלים:

ההתאמה של נתיבים היא תלוית אותיות רישיות.
אם הקידומת זהה לכתובת ה-URL, יש התאמה.
אם כתובת ה-URL זהה לתחילית או שהיא צאצא שלה, היא תואמת.

לדוגמה, הקידומת https://example.com/foo תואמת לכתובות ה-URL הבאות:

https://example.com/foo
https://example.com/foo/
https://example.com/foo/bar
https://example.com/foo?bar
https://example.com/foo#bar

שימוש בתווים כלליים

אפשר להשתמש בתו כללי לחיפוש (*) כדי להתאים תת-דומיין בשדות urlFetchWhitelist ו-addOns.common.openLinkUrlPrefixes. אי אפשר להשתמש ביותר מתו כללי אחד כדי להתאים לכמה תת-דומיינים, והתו הכללי חייב לייצג את הקידומת המובילה של כתובת ה-URL.

לדוגמה, הקידומת https://*.example.com/foo תואמת לכתובות ה-URL הבאות:

https://subdomain.example.com/foo
https://any.number.of.subdomains.example.com/foo

הקידומת https://*.example.com/foo לא תואמת לכתובות ה-URL הבאות:

https://subdomain.example.com/bar (אי התאמה בסיומת)
‫https://example.com/foo (צריך לציין לפחות תת-דומיין אחד)

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

https://*.*.example.com/foo (אסור להשתמש בכמה תווים כלליים לחיפוש)
https://subdomain.*.example.com/foo (חובה להשתמש בתווים כלליים לחיפוש כקידומת מובילה)