Расширение пользовательского интерфейса сообщений

Дополнения Google Workspace, расширяющие Gmail, могут предоставлять пользовательский интерфейс, когда пользователь читает сообщения. Это позволяет надстройкам Google Workspace автоматизировать задачи, которые реагируют на содержимое сообщения, например отображение, получение или отправку дополнительной информации, связанной с сообщением.

Доступ к пользовательскому интерфейсу дополнительных сообщений

Существует два способа просмотра пользовательского интерфейса сообщений надстройки. Первый способ — открыть сообщение, когда надстройка уже открыта (например, при просмотре домашней страницы надстройки в окне «Входящие» Gmail). Второй способ — запустить дополнение во время просмотра сообщения.

В любом случае надстройка выполняет соответствующую контекстную триггерную функцию , определенную в манифесте надстройки. Триггер также срабатывает, если пользователь переключается на другое сообщение, пока надстройка все еще открыта. Функция контекстного триггера создает пользовательский интерфейс для этого сообщения, который Gmail затем отображает пользователю.

Создание дополнения к сообщению

Вы можете добавить функциональность сообщений в надстройку, выполнив следующие общие шаги:

1. Добавьте соответствующие поля в манифест проекта дополнительного скрипта, включая области, необходимые для функциональности сообщений. Обязательно добавьте в манифест поле условного триггера с unconditional значением {} .
2. Реализуйте контекстную триггерную функцию, которая создает пользовательский интерфейс сообщения, когда пользователь выбирает надстройку в сообщении.
3. Реализуйте связанные функции, необходимые для реагирования на взаимодействия пользователя с пользовательским интерфейсом.

Контекстные триггеры

Чтобы предоставить пользователям помощь при чтении сообщений, надстройки Google Workspace могут определять контекстный триггер в своих манифестах. Когда пользователь открывает сообщение Gmail (с открытым дополнением), соответствующее критериям триггера *, триггер срабатывает. Запущенный триггер выполняет контекстную функцию триггера , которая создает пользовательский интерфейс надстройки и возвращает его для отображения в Gmail. На этом этапе пользователь может начать с ним взаимодействовать.

Контекстные триггеры определяются в манифесте проекта вашего дополнения. Определение триггера сообщает Gmail, какую функцию триггера запускать и при каких условиях. Например, этот фрагмент манифеста устанавливает безусловный триггер, который вызывает триггерную функцию onGmailMessageOpen() при открытии сообщения:

{
  ...
  "addOns": {

    "common": {
      ...
    },
    "gmail": {
      "contextualTriggers": [
        {
          "unconditional": {},
          "onTriggerFunction": "onGmailMessageOpen"
        }
      ],
      ...
    },
    ...
  }
  ...
}

В настоящее время единственным доступным типом контекстного триггера является unconditional , который срабатывает для всех электронных писем независимо от их содержания.

Контекстная триггерная функция

Каждый контекстный триггер должен иметь соответствующую триггерную функцию , которая создает пользовательский интерфейс вашей надстройки. Вы указываете эту функцию в поле onTriggerFunction вашего манифеста. Вы реализуете эту функцию, чтобы принять аргумент объекта события действия и вернуть либо один объект Card , либо массив объектов Card .

Когда для данного сообщения Gmail срабатывает контекстный триггер, он вызывает эту функцию и передает ей объект события действия . Часто триггерные функции используют идентификатор сообщения, предоставленный этим объектом события, для получения текста сообщения и других сведений с помощью службы Gmail Apps Script. Например, ваша триггерная функция может извлекать содержимое сообщения, используя следующие функции:

  // Activate temporary Gmail scopes, in this case to allow
  // the add-on to read message metadata and content.
  var accessToken = e.gmail.accessToken;
  GmailApp.setCurrentMessageAccessToken(accessToken);

  // Read message metadata and content. This requires the Gmail scope
  // https://www.googleapis.com/auth/gmail.addons.current.message.readonly.
  var messageId = e.gmail.messageId;
  var message = GmailApp.getMessageById(messageId);
  var subject = message.getSubject();
  var sender = message.getFrom();
  var body = message.getPlainBody();
  var messageDate = message.getDate();

  // Setting the access token with a gmail.addons.current.message.readonly
  // scope also allows read access to the other messages in the thread.
  var thread = message.getThread();
  var threadMessages = thread.getMessages();

  // Using this link can avoid the need to copy message or thread content
  var threadLink = thread.getPermalink();

Примечание. В большинстве случаев перед использованием других функций службы Gmail необходимо активировать области Gmail , используя токен доступа, предоставленный объектом события, и функцию GmailApp.setCurrentMessageAccessToken(accessToken) .

Затем триггерная функция может воздействовать на эти данные, извлекая информацию, необходимую для интерфейса. Например, надстройка, суммирующая данные о продажах, может собирать данные о продажах из тела сообщения и организовывать их для отображения на карточке .

Триггерная функция должна создать и вернуть массив построенных объектов Card . Например, следующее создает надстройку с одной карточкой, в которой просто указана тема и отправитель сообщения:

  function onGmailMessageOpen(e) {
    // Activate temporary Gmail scopes, in this case to allow
    // message metadata to be read.
    var accessToken = e.gmail.accessToken;
    GmailApp.setCurrentMessageAccessToken(accessToken);

    var messageId = e.gmail.messageId;
    var message = GmailApp.getMessageById(messageId);
    var subject = message.getSubject();
    var sender = message.getFrom();

    // Create a card with a single card section and two widgets.
    // Be sure to execute build() to finalize the card construction.
    var exampleCard = CardService.newCardBuilder()
        .setHeader(CardService.newCardHeader()
            .setTitle('Example card'))
        .addSection(CardService.newCardSection()
            .addWidget(CardService.newKeyValue()
                .setTopLabel('Subject')
                .setContent(subject))
            .addWidget(CardService.newKeyValue()
                .setTopLabel('From')
                .setContent(sender)))
        .build();   // Don't forget to build the Card!
    return [exampleCard];
  }