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

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

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

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

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

Создание дополнения для отправки сообщений

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

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

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

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

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

{
  ...
  "addOns": {

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

Функция контекстного запуска

Каждый контекстный триггер должен иметь соответствующую функцию-триггер , которая формирует пользовательский интерфейс вашего дополнения. Вы указываете эту функцию в поле 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();

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

Функция-триггер должна создавать и возвращать массив созданных объектов 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];
  }