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 en détail comment configurer un fichier manifeste pour un module complémentaire Google Workspace.

Structure du fichier manifeste pour les modules complémentaires Google Workspace

Les modules complémentaires Google Workspace utilisent le fichier manifeste pour définir plusieurs aspects de l'apparence et du comportement du module complémentaire.

Les propriétés du fichier manifeste pour les modules complémentaires Google Workspace sont organisées dans la section addOns de la structure de l'objet manifeste.

• Pour en savoir plus sur les fichiers manifestes Apps Script, consultez Structure du fichier manifeste.

• Pour en savoir plus sur les fichiers manifestes des modules complémentaires créés avec des points de terminaison HTTP, consultez la ressource projects.deployments.

Manifestes pour Google Chat

Si votre module complémentaire Google Workspace étend Google Chat, vous devez configurer 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 fichier manifeste (y compris addons.common) sont ignorés dans Chat. Au lieu d'utiliser le fichier manifeste du module complémentaire, vous utilisez l'API Chat pour configurer les paramètres Chat suivants :

• Le nom, le logo et la description de l'application Chat, qui n'apparaissent que dans l'interface utilisateur de Chat.
• Déclencheurs d'application de chat

Si vous avez créé le module complémentaire dans Apps Script, vous devez également ajouter ou mettre à jour les objets suivants dans votre fichier manifeste :

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

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

Exemple de configuration du fichier manifeste d'un module complémentaire Google Workspace

Les exemples de fichiers manifestes suivants montrent la section d'un fichier manifeste qui définit un module complémentaire Google Workspace, y compris les aspects suivants :

• La section addOns.common du fichier manifeste définit le nom, l'URL du logo, les couleurs et d'autres paramètres généraux indépendants de l'hôte pour le module complémentaire.

• Le fichier manifeste définit une page d'accueil commune, mais aussi des pages d'accueil spécifiques à Agenda, Drive, Docs, Sheets et Slides. Gmail utilise la page d'accueil par défaut.

• Les paramètres de l'exemple de fichier manifeste permettent les actions suivantes :

  • Déclencheurs Agenda eventOpen et eventUpdated.

  • (Apps Script uniquement) Deux solutions de visioconférence Calendar.

  • Deux actions universelles.

  • A Drive onItemsSelectedTrigger.

  • Action de rédaction d'un e-mail Gmail et déclencheur contextuel.

  • Un objet linkPreviewTriggersDocs. Pour en savoir plus sur ce déclencheur, consultez Prévisualiser les liens avec les chips intelligents.

  • Objet createActionTriggers Docs. Pour en savoir plus sur ce déclencheur, consultez Créer des ressources tierces à partir du menu @.

  • Interfaces spécifiques aux fichiers pour Docs, Sheets et Slides.

  • (HTTP uniquement) Deux HttpOptions pour envoyer un en-tête d'autorisation et accepter le consentement précis.

• Le champ oauthScopes définit les niveaux d'autorisation pour le projet (généralement requis pour les modules complémentaires).

• (Apps Script uniquement) Le champ urlFetchWhitelist permet de s'assurer que tous les points de terminaison récupérés correspondent à une liste spécifiée de préfixes d'URL HTTPS. Pour en savoir plus, consultez Ajouter des URL à la liste d'autorisation.

Les liens dans les exemples de fichier manifeste redirigent vers les descriptions de ce champ dans la documentation de référence du fichier manifeste correspondant pour les modules complémentaires Google Workspace Apps Script et HTTP.

Remarque : Les fichiers manifestes incluent d'autres composants. Les champs sous le champ addOns sont directement liés aux modules complémentaires Google Workspace. Cet exemple n'est qu'une partie d'un fichier manifeste complet et n'est pas un manifeste entièrement fonctionnel.

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"
      }
    }
  },
  "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"
      }
    }
    "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"
  ]
}

Ajouter des URL à la liste d'autorisation

Les listes d'autorisation vous permettent de 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 utilisateur. Lorsque vous définissez une liste d'autorisation, les projets de script ne peuvent pas accéder aux URL qui n'y ont pas été ajoutées.

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

Vous utilisez des listes d'autorisation lorsque votre script ou votre 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 champ 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 l'ouverture d'URL, incluez le champ addOns.common.openLinkUrlPrefixes dans votre fichier manifeste.

Remarque : Le terme liste blanche, tel qu'il est utilisé dans urlFetchWhitelist, est obsolète. Il est synonyme de liste d'autorisation et a été remplacé par ce terme. Pour en savoir plus, consultez Rédiger une documentation inclusive.

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 fichier 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 comporter un domaine complet.
• Chaque préfixe doit comporter un chemin 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-domaines d'URL.
• Un seul caractère générique * peut être utilisé dans le champ addOns.common.openLinkUrlPrefixes pour 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 des modules complémentaires. N'utilisez un caractère générique que si la fonctionnalité de votre module complémentaire l'exige.

Les règles suivantes s'appliquent pour déterminer si une URL correspond à un préfixe dans la liste d'autorisation :

• 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 est un enfant du préfixe, elle correspond.

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 plusieurs caractères génériques pour faire correspondre plusieurs sous-domaines. De plus, le caractère générique doit représenter le préfixe de début 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 incorrect)
• https://example.com/foo (au moins un sous-domaine doit être présent)

Certaines règles de préfixe sont appliquées lorsque vous essayez d'enregistrer votre fichier manifeste. Par exemple, les préfixes suivants entraînent une erreur s'ils sont présents dans votre fichier 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)