Note: We are still rolling out some features of G Suite Add-ons. You can start developing new G Suite add-ons, but may be unable to test them until the rollout is complete in early February 2020.

Triggers for G Suite add-ons

Apps Script triggers cause a specified script function (the trigger function) to execute whenever a specified event occurs. Only certain events can cause triggers to fire, and each G Suite application supports a different set of events.

When a trigger fires, an event object is created. This JSON structure contains details about the event that occurred. The information in the event object structure is organized differently based on the trigger type.

Once the event object is created, Apps Script passes it as a parameter to the trigger function. The trigger function is a callback function that you must implement yourself, to take whatever actions are appropriate to respond to the event. For example, in a G Suite add-on that extends Gmail, you can define a trigger that creates a new card interface when the user opens a message thread. In this case, you implement a contextual callback function to create the cards making up the new UI using the data passed in the event object.

This page provides guidelines on using triggers in G Suite add-on projects.

Manifest triggers

Unlike editor add-ons, G Suite add-ons currently can't use generic Apps Script simple triggers or installable triggers. Instead, they use triggers designed specifically for G Suite add-ons: manifest triggers.

Manifest triggers are defined completely in the G Suite add-on's manifest. Examples of manifest triggers include the following:

  • Homepage triggers that build and display the add-on homepage.
  • Calendar eventOpen triggers that display a new card or take other actions when a Calendar event is opened.
  • Calendar eventUpdate triggers that display a new card or take other actions when a user edits and saves a Calendar event.
  • Drive onItemsSelected triggers that display a new card or take other actions when a user selects one or more files or folders in Drive.
  • Gmail compose triggers that display an add-on card when the user opens the add-on in the Gmail compose window.
  • Gmail contextual triggers that display a new card or take other actions when the user opens a Gmail message.

In the above list, only homepage triggers are non-contextual; the rest are contextual triggers. See Manifest for more information about manifest trigger definitions.

Restrictions

Manifest triggers have certain restrictions to their use.

  • These triggers are only used in G Suite add-on projects; they have no purpose in any other application.
  • Since they are defined in the add-on manifest and not in its code, you can't use the Apps Script Script service to create or modify these triggers.
  • Gmail contextual triggers currently can only have an unconditional criteria. This means contextual triggers fire for every email message, regardless of content.