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

Надстройки 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];
  }