מניפסטים של תוספים ל-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 (חובה להשתמש בתווים כלליים לחיפוש כקידומת מובילה)