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

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

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

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

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

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

  • מידע על קובצי מניפסט של Apps Script זמין במאמר בנושא מבנה המניפסט.

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

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

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

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

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

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

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

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

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

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

  • קובץ המניפסט מגדיר דף בית משותף, אבל הוא גם מגדיר דפי בית ספציפיים ליומן Google, ל-Google Drive, ל-Google Docs, ל-Sheets ול-Slides. ‫Gmail משתמש בדף הבית שמוגדר כברירת מחדל.

  • הגדרות קובץ המניפסט לדוגמה מאפשרות את הפעולות הבאות:

  • בשדה oauthScopes מגדירים את היקפי ההרשאות של הפרויקט (בדרך כלל נדרש לתוספים).

  • (Apps Script בלבד) השדה urlFetchWhitelist הוא שדה שמוודא שכל נקודות הקצה שאוחזרו תואמות לרשימה שצוינה של קידומות של כתובות URL מסוג HTTPS. מידע נוסף זמין במאמר בנושא יצירת רשימת היתרים של כתובות URL.

הקישורים בדוגמאות למניפסט מפנים לתיאורים של השדה הזה במסמכי העיון הרלוונטיים למניפסט של תוספים ל- Apps Script ול-HTTP ב-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 (חובה להשתמש בתווים כלליים לחיפוש כקידומת מובילה)