Rozszerzanie interfejsu wiadomości

Dodatki do Google Workspace, które rozszerzają funkcje Gmaila, mogą wyświetlać interfejs, gdy użytkownik czyta wiadomości. Dzięki temu dodatki do Google Workspace mogą zautomatyzować zadania, które odpowiadają na treść wiadomości, takie jak wyświetlanie, pobieranie czy wysyłanie dodatkowych informacji związanych z wiadomością.

Uzyskiwanie dostępu do interfejsu wiadomości dodatku

Interfejs wiadomości dodatku można wyświetlić na 2 sposoby. Pierwszym sposobem jest otwarcie wiadomości, gdy dodatek jest już otwarty (na przykład podczas wyświetlania strony głównej dodatku w oknie skrzynki odbiorczej Gmaila). Drugi sposób to uruchomienie dodatku podczas wyświetlania wiadomości.

W obu przypadkach dodatek uruchamia odpowiednią funkcję aktywatora kontekstowego zdefiniowaną w pliku manifestu dodatku. Aktywator jest też uruchamiany, gdy użytkownik przełączy się na inną wiadomość, gdy dodatek jest nadal uruchomiony. Funkcja aktywatora kontekstowego tworzy interfejs tej wiadomości, który Gmail wyświetla użytkownikowi.

Tworzenie dodatku do wysyłania wiadomości

Aby dodać funkcję wiadomości do dodatku, wykonaj te ogólne czynności:

  1. Dodaj odpowiednie pola do pliku manifestu skryptu dodatku, w tym zakresy wymagane do działania wiadomości. Pamiętaj, aby do pliku manifestu dodać pole aktywatora warunkowego z wartością unconditional {}.
  2. Zaimplementuj funkcję aktywatora kontekstowego, która tworzy interfejs użytkownika wiadomości, gdy użytkownik wybierze dodatek w wiadomości.
  3. Zaimplementuj powiązane funkcje niezbędne do reagowania na interakcje użytkownika z interfejsem użytkownika.

Reguły kontekstowe

Aby zapewnić użytkownikom pomoc podczas odczytywania wiadomości, dodatki do Google Workspace mogą zdefiniować aktywator kontekstowy w plikach manifestu. Gdy użytkownik otworzy wiadomość w Gmailu (z otwartym dodatkiem), która spełnia kryteria aktywatora* uruchamiane przez regułę. Uruchomiony aktywator wykonuje funkcję aktywatora kontekstowego, która tworzy interfejs dodatku, a następnie zwraca ją do Gmaila. W tym momencie użytkownik może zacząć z niego korzystać.

Aktywatory kontekstowe są zdefiniowane w pliku manifestu projektu dodatku. Definicja aktywatora informuje Gmaila, która funkcja aktywująca ma być uruchamiana w określonych warunkach. Na przykład ten fragment kodu manifestu ustawia wyzwalacz bezwarunkowy, który wywołuje funkcję aktywatora onGmailMessageOpen() po otwarciu wiadomości:

{
  ...
  "addOns": {

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

Funkcja aktywatora kontekstowego

Każdy aktywator kontekstowy musi mieć odpowiadającą jej funkcję aktywatora, która tworzy interfejs użytkownika dodatku. Tę funkcję musisz określić w polu onTriggerFunction manifestu. Zaimplementujesz tę funkcję, by zaakceptować argument obiektu zdarzenia działania i zwrócić pojedynczy obiekt Card lub tablicę obiektów Card.

Gdy reguła kontekstowa jest uruchamiana w przypadku określonej wiadomości w Gmailu, wywołuje tę funkcję i przekazuje ją obiekt zdarzenia czynności. Funkcje aktywujące często używają identyfikatora wiadomości podawanego przez ten obiekt zdarzenia, aby pobrać tekst wiadomości i inne szczegóły za pomocą usługi Gmail Apps Script. Funkcja aktywująca może na przykład wyodrębnić treść wiadomości za pomocą tych funkcji:

  // 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();

Funkcja aktywująca może następnie działać na tych danych, wyodrębniając informacje potrzebne interfejsowi. Na przykład dodatek podsumowujący dane sprzedaży może zbierać dane dotyczące sprzedaży z treści wiadomości i porządkować je na karcie.

Funkcja aktywatora musi skompilować i zwrócić tablicę skompilowanych obiektów Card. W ten sposób utworzysz dodatek z 1 kartą, która zawiera tylko temat i nadawcę wiadomości:

  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];
  }