Fichiers manifestes pour les modules complémentaires Google Workspace

Un module complémentaire utilise un fichier manifeste pour configurer certains détails concernant l'application et son fonctionnement.

Cette documentation explique comment configurer un manifeste pour un module complémentaire Google Workspace.

Structure du manifeste pour les modules complémentaires Google Workspace

Les modules complémentaires Google Workspace utilisent le fichier manifeste pour définir plusieurs aspects de leur apparence et de leur comportement.

Les propriétés du manifeste pour les modules complémentaires Google Workspace sont organisées sous la section addOns.

Pour en savoir plus sur les fichiers manifestes Google Apps Script, consultez Structure du manifeste.
Pour en savoir plus sur les fichiers manifestes des modules complémentaires créés avec des points de terminaison HTTP, consultez projects.deployments.

Manifestes pour Google Chat

Si votre module complémentaire Google Workspace étend Google Chat, configurez une application Google Chat en activant et en configurant l'API Google Chat dans la console Google Cloud.

Les paramètres de configuration courants du manifeste (y compris addons.common) sont ignorés dans Chat. Utilisez l'API Chat pour configurer les paramètres Chat suivants :

Le nom, le logo et la description de l'application Chat pour l'interface Chat.
Les déclencheurs de l'application Chat.

Si vous avez créé le module complémentaire dans Apps Script, ajoutez ou mettez à jour les objets suivants dans votre manifeste :

addons.chat (obligatoire)
oauthScopes (obligatoire si votre application Google Chat utilise OAuth)

Pour configurer les paramètres Chat d'un module complémentaire, consultez Configurer une application Google Chat.

Exemple de configuration de manifeste de module complémentaire Google Workspace

Les exemples suivants montrent la partie d'un manifeste qui définit un module complémentaire Google Workspace, y compris les aspects suivants :

addOns.common définit le nom, le logo, les couleurs et d'autres paramètres généraux du module complémentaire.
Le manifeste définit une page d'accueil commune, mais aussi des pages d'accueil spécifiques à Google Agenda, Google Drive, Google Docs, Google Sheets et Google Slides. Gmail utilise la page d'accueil par défaut.
Les paramètres de l'exemple de manifeste activent les éléments suivants :
- Les déclencheurs eventOpen et eventUpdated de l'agenda.
- (Apps Script uniquement) Deux solutions de conférence pour l'agenda .
- Deux actions universelles.
- Un onItemsSelectedTrigger Drive.
- Une action de rédaction et un déclencheur contextuel Gmail.
- Un objet linkPreviewTriggers Docs. Consultez Prévisualiser les liens avec les chips intelligents.
- Un objet createActionTriggers Docs. Consultez Créer des ressources tierces à partir du menu @.
- Des interfaces spécifiques aux fichiers pour Docs, Sheets et Slides.
- Une option sidePanelUri et addOnOrigins Google Meet.
- (HTTP uniquement) Deux HttpOptions pour envoyer un en-tête d'autorisation et prendre en charge le consentement précis.
Le champ oauthScopes définit les autorisations du projet.
(Apps Script uniquement) urlFetchWhitelist garantit que les points de terminaison récupérés correspondent aux préfixes d'URL HTTPS spécifiés. Consultez URL sur liste d'autorisation.

Les liens des exemples redirigent vers les descriptions des champs de la documentation de référence sur le manifeste pour les modules complémentaires Apps Script et HTTP Google Workspace.

Les manifestes incluent d'autres composants. Les champs sous addOns sont directement liés aux modules complémentaires Google Workspace. Cet exemple ne montre qu'une partie d'un fichier manifeste complet et n'est pas fonctionnel seul.

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 sur liste d'autorisation

Vous utilisez des listes d'autorisation pour désigner des URL spécifiques qui sont pré-approuvées pour l'accès par votre script ou module complémentaire. Les listes d'autorisation permettent de protéger les données des utilisateurs. Lorsque vous définissez une liste d'autorisation, les projets de script ne peuvent pas accéder aux URL qui n'ont pas été ajoutées à la liste d'autorisation.

Ce champ est facultatif lorsque vous installez un déploiement de test, mais il est obligatoire lorsque vous créez un déploiement avec version.

Vous utilisez des listes d'autorisation lorsque votre script ou module complémentaire effectue les actions suivantes :

Récupère des informations à partir d'un emplacement externe (tel que des points de terminaison HTTPS ) à l'aide du service UrlFetch Apps Script. Pour autoriser les URL à être récupérées, incluez le urlFetchWhitelist dans votre fichier manifeste.
Ouvre ou affiche une URL en réponse à une action de l'utilisateur (obligatoire pour les modules complémentaires Google Workspace qui ouvrent ou affichent des URL externes à Google). Pour autoriser les URL à être ouvertes, incluez le addOns.common.openLinkUrlPrefixes champ dans votre fichier manifeste.

Ajouter des préfixes à votre liste d'autorisation

Lorsque vous spécifiez des listes d'autorisation dans votre fichier manifeste (en incluant le champ addOns.common.openLinkUrlPrefixes ou urlFetchWhitelist), vous devez inclure une liste de préfixes d'URL. Les préfixes que vous ajoutez au manifeste doivent répondre aux exigences suivantes :

Chaque préfixe doit être une URL valide.
Chaque préfixe doit utiliser https:// et non http://.
Chaque préfixe doit avoir un domaine complet.
Chaque préfixe doit avoir un chemin d'accès non vide. Par exemple, https://www.google.com/ est valide, mais https://www.google.com ne l'est pas.
Vous pouvez utiliser des caractères génériques pour faire correspondre les préfixes de sous-domaine d'URL.
Un seul caractère générique * peut être utilisé dans le addOns.common.openLinkUrlPrefixes champ pour faire correspondre tous les liens, mais cela n'est pas recommandé, car cela peut exposer les données d'un utilisateur à des risques et prolonger le processus d'examen du module complémentaire. N'utilisez un caractère générique que si la fonctionnalité de votre module complémentaire l'exige.

Lorsque vous déterminez si une URL correspond à un préfixe dans la liste d'autorisation, les règles suivantes s'appliquent :

La mise en correspondance des chemins d'accès est sensible à la casse.
Si le préfixe est identique à l'URL, il y a correspondance.
Si l'URL est identique au préfixe ou à un enfant de celui-ci, il y a correspondance.

Par exemple, le préfixe https://example.com/foo correspond aux URL suivantes :

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

Utiliser des caractères génériques

Vous pouvez utiliser un seul caractère générique (*) pour faire correspondre un sous-domaine pour les champs urlFetchWhitelist et addOns.common.openLinkUrlPrefixes. Vous ne pouvez pas utiliser plus d'un caractère générique pour faire correspondre plusieurs sous-domaines, et le caractère générique doit représenter le préfixe principal de l'URL.

Par exemple, le préfixe https://*.example.com/foo correspond aux URL suivantes :

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

Le préfixe https://*.example.com/foo ne correspond pas aux URL suivantes :

https://subdomain.example.com/bar (suffixe non correspondant)
https://example.com/foo (au moins un sous-domaine doit être présent)

Certaines règles de préfixe sont appliquées lorsque vous tentez d'enregistrer votre manifeste. Par exemple, les préfixes suivants provoquent une erreur s'ils sont présents dans votre manifeste lorsque vous tentez d'enregistrer :

https://*.*.example.com/foo (plusieurs caractères génériques sont interdits)
https://subdomain.*.example.com/foo (les caractères génériques doivent être utilisés comme préfixe principal)