Objets d'événement

Cette page décrit la structure des objets d'événement des modules complémentaires Google Workspace.

Les objets d'événement sont des structures JSON qui sont automatiquement construites et transmises en tant que paramètres pour déclencher ou rappeler des fonctions lorsqu'un utilisateur interagit avec un module complémentaire. Les objets d'événement transmettent des informations côté client concernant l'application hôte et le contexte actuel à la fonction de rappel côté serveur du module complémentaire.

Les modules complémentaires Google Workspace utilisent des objets d'événement aux emplacements suivants:

• Déclencheurs de la page d'accueil : Chaque fonction homepageTrigger que vous définissez reçoit automatiquement un objet événement lorsque la fonction du déclencheur de la page d'accueil est exécutée. Vous pouvez utiliser cet objet dans la fonction de déclenchement de votre page d'accueil pour identifier l'application hôte active, la plate-forme du client, les paramètres régionaux de l'utilisateur et d'autres informations.

  Les objets d'événement créés lors du déclenchement de la page d'accueil ne contiennent pas tous les champs inclus dans les deux autres cas. Les champs concernant les widgets et les informations contextuelles sont omis.

• Déclencheurs contextuels : Chaque application hôte fournit un ensemble différent de déclencheurs contextuels qui se déclenchent lorsque l'utilisateur entre dans un contexte spécifique. Exemple :

  • Gmail fournit un déclencheur contextuel lorsqu'un utilisateur ouvre un message et un autre lorsqu'un utilisateur rédige un message.
  • Google Agenda fournit un déclencheur contextuel lorsqu'un utilisateur ouvre un événement.
  • Google Drive fournit un déclencheur contextuel lorsqu'un utilisateur sélectionne des fichiers Drive.

  Lorsqu'un déclencheur contextuel s'exécute, l'application hôte appelle le runFunction correspondant listé dans le fichier manifeste du module complémentaire, en lui transmettant un objet d'événement en tant que paramètre. Les objets d'événement créés lorsque des déclencheurs contextuels sont déclenchés contiennent tous les champs inclus dans les objets d'événement de déclencheur de la page d'accueil, ainsi que des champs contenant des informations contextuelles.

• Actions du widget. Les objets d'événement permettent également de fournir une interactivité au niveau des widgets, à l'aide du même modèle d'action que celui utilisé par les modules complémentaires Gmail. Les modules complémentaires Google Workspace utilisent les mêmes fonctions de gestionnaire de widgets, objets Action et réponses d'action. Toutefois, dans les modules complémentaires Google Workspace, les objets d'événement d'action incluent encore plus d'informations sur lesquelles une fonction de rappel peut agir.

  Les objets d'événement créés à la suite d'actions de widget contiennent tous les champs inclus dans les objets d'événement de déclencheur contextuel, ainsi que des champs contenant des informations sur les widgets.

• Déclencheurs du lien d'aperçu : Dans Google Docs, Sheets et Slides, vous pouvez configurer des aperçus de liens pour des services tiers en fonction de formats d'URL spécifiques. Lorsque les utilisateurs interagissent avec un lien qui correspond au modèle, linkPreviewTriggers se déclenche et un objet d'événement contenant le lien est transmis à la fonction de rappel du déclencheur. Votre module complémentaire peut utiliser cet objet d'événement pour créer un chip intelligent et une carte qui affichent des informations sur le lien dans l'application hôte. Vous pouvez également créer des actions de widget pour permettre aux utilisateurs d'interagir avec la fiche d'aperçu et son contenu.

Structure de l'objet de l'événement

Le tableau suivant décrit la structure de premier niveau des objets d'événement des modules complémentaires Google Workspace. La structure d'objet d'événement inclut un champ commonEventObject de niveau supérieur pour les informations indépendantes de l'hôte. Chaque objet d'événement peut également comporter l'un des champs de premier niveau suivants, spécifiques à l'hôte, déterminés par l'application hôte active: gmailEventObject, calendarEventObject ou driveEventObject.

Pour assurer la rétrocompatibilité, les objets d'événement des modules complémentaires Google Workspace incluent également tous les champs d'origine utilisés dans les objets d'événement d'action des modules complémentaires Gmail. Ces champs sont répertoriés dans le tableau ci-dessous, sous "Champs d'origine des modules complémentaires Gmail". Les informations qu'ils contiennent sont reproduites dans la nouvelle structure d'objets.

Objet d'événement commun

L'objet d'événement commun est la partie de l'objet d'événement global qui transmet au module complémentaire des informations générales indépendantes de l'hôte à partir du client de l'utilisateur. Ces informations incluent des détails tels que les paramètres régionaux de l'utilisateur, l'application hôte et la plate-forme.

En plus des déclencheurs de page d'accueil et de contexte, les modules complémentaires construisent et transmettent des objets d'événement aux fonctions de rappel d'action lorsque l'utilisateur interagit avec les widgets. La fonction de rappel de votre module complémentaire peut interroger l'objet d'événement commun pour déterminer le contenu des widgets ouverts dans le client de l'utilisateur. Par exemple, votre module complémentaire peut localiser le texte qu'un utilisateur a saisi dans un widget TextInput de l'objet eventObject.commentEventObject.formInputs.

Entrées du formulaire pour le sélecteur de date et d'heure

Les fonctions de rappel d'action peuvent recevoir les valeurs actuelles de widget dans le champ commonEventObject.formInputs. Cela inclut les valeurs de date ou d'heure sélectionnées par l'utilisateur dans les widgets de sélecteur de date ou d'heure. Cependant, la structure des informations diffère selon que le widget a été configuré en tant que sélecteur de date/heure, de sélecteur de date uniquement ou de sélecteur d'heure. Les différences structurelles sont décrites dans le tableau suivant:

Objet d'événement d'agenda

L'objet événement d'agenda correspond à la partie de l'objet d'événement global qui contient des informations sur l'agenda et les événements d'agenda d'un utilisateur. Il n'est présent dans un objet événement que si l'application hôte est Google Agenda.

Le tableau suivant répertorie les champs présents dans le champ calendarEventObject d'un objet événement. Les champs marqués comme Données générées par l'utilisateur sont présents dans l'objet événement si et seulement si les données sont présentes dans l'événement Agenda et si le module complémentaire définit son champ manifest addOns.calendar.currentEventAccess sur READ ou READ_WRITE.

Participant

Les objets Attendee transmettent des informations sur chaque participant dans les événements Google Agenda. Ces informations ne sont présentes dans l'objet événement que si les données sont présentes dans l'événement Agenda et si le module complémentaire définit son champ manifest addOns.calendar.currentEventAccess sur READ ou READ_WRITE.

Données de conférence

Les objets de données de conférence contiennent des informations sur les conférences associées aux événements Google Agenda. Il peut s'agir de solutions de conférence Google, telles que Google Meet, ou de conférences tierces. Ces informations ne sont présentes dans l'objet d'événement que si les données sont présentes dans l'événement Agenda et si le module complémentaire définit son champ manifest addOns.calendar.currentEventAccess sur READ ou READ_WRITE.

le point d'entrée,

Les objets de point d'entrée contiennent des informations sur le moyen établi d'accéder à une conférence donnée, par exemple par téléphone ou par vidéo. Ces informations ne sont présentes dans l'objet événement que si les données sont présentes dans l'événement Agenda et si le module complémentaire définit son champ manifest addOns.calendar.currentEventAccess sur READ ou READ_WRITE.

Objet d'événement Drive

L'objet d'événement Drive correspond à la partie de l'objet d'événement global qui contient des informations sur le Google Drive d'un utilisateur et son contenu. Il n'est présent dans un objet événement que si l'application hôte est Google Drive.

Élément Drive

Les objets Drive contiennent des informations sur des éléments Drive spécifiques tels que des fichiers ou des dossiers.

Objet d'événement Gmail

L'objet d'événement Gmail correspond à la partie de l'objet d'événement global qui contient des informations sur les messages Gmail d'un utilisateur. Il n'est présent dans un objet événement que si l'application hôte est Gmail.

Objet d'événement Docs

L'objet d'événement Docs est la partie de l'objet d'événement global qui contient des informations sur le document d'un utilisateur et son contenu. Il n'est présent dans un objet d'événement que si l'application hôte est Google Docs.

"docs" : {
  "matchedUrl" : {
      "url" : "https://www.example.com/12345"
  }
}
        

Objet d'événement Sheets

L'objet d'événement Sheets correspond à la partie de l'objet d'événement global qui contient des informations sur le document d'un utilisateur et son contenu. Il n'est présent dans un objet d'événement que si l'application hôte est Google Sheets.

"sheets" : {
  "matchedUrl" : {
      "url" : "https://www.example.com/12345"
  }
}
        

Objet d'événement Slides

L'objet d'événement Slides correspond à la partie de l'objet d'événement global qui contient des informations sur le document d'un utilisateur et son contenu. Il n'est présent dans un objet d'événement que si l'application hôte est Google Slides.

"slides" : {
  "matchedUrl" : {
      "url" : "https://www.example.com/12345"
  }
}