Rozszerzanie interfejsu wiadomości

Google Workspace Dodatki, które rozszerzają możliwości Gmaila, mogą udostępniać interfejs użytkownika, gdy czyta on wiadomość. Dzięki temuGoogle Workspace dodatki mogą zautomatyzować zadania, które reagują na treść wiadomości, takie jak wyświetlanie, pobieranie lub wysyłanie dodatkowych informacji związanych z wiadomością.

Dostęp do interfejsu dodatku dodatku

Istnieją 2 sposoby wyświetlania interfejsu wiadomości dodatku. Pierwszym sposobem jest otwarcie wiadomości w czasie, 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 funkcję aktywowania kontekstowego, która jest zdefiniowana w pliku manifestu dodatku. Aktywator zostanie uruchomiony, jeśli użytkownik przełączy się na inną wiadomość, gdy dodatek jest nadal otwarty. Funkcja reguły kontekstowej tworzy interfejs wiadomości, który Gmail wyświetla użytkownikowi.

Tworzenie dodatku do wiadomości

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

  1. Dodaj odpowiednie pola do pliku manifestu projektu dodatku, uwzględniając zakresy wymagane do działania funkcji wiadomości. Pamiętaj, aby do pliku manifestu dodać pole aktywatora warunkowego o wartości unconditional ({}).
  2. Zaimplementuj funkcję kontekstowego kierowania reklamy, która skompiluje interfejs wiadomości, gdy użytkownik wybierze dodatek w wiadomości.
  3. Zaimplementować powiązane funkcje niezbędne do reakcji na interakcje użytkownika z interfejsu.

Reguły kontekstowe

Aby zapewnić użytkownikom pomoc przy odczytywaniu wiadomości, Google Workspace dodatki mogą określać reguły kontekstowe w plikach manifestu. Gdy użytkownik otworzy wiadomość w Gmailu (z dodatkiem), który spełnia kryteria reguły*. Uruchomiony aktywator uruchamia kontekstową funkcję aktywatora, która kompiluje interfejs użytkownika dodatku i zwraca go, aby Gmail mógł go wyświetlić. Od tego momentu użytkownik może zacząć korzystać z aplikacji.

Aktywatory kontekstowe są zdefiniowane w pliku manifestu projektu dodatku. Definicja aktywatora informuje Gmaila, która funkcja uruchamia się pod określonymi warunkami. Na przykład ten fragment pliku manifestu ustawia bezwarunkowy aktywator, który po otwarciu wiadomości wywołuje funkcję onGmailMessageOpen():

{
  ...
  "addOns": {

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

Funkcja aktywatora kontekstowego

Każda reguła kontekstowa musi mieć odpowiadającą jej funkcję reguł tworzącą interfejs użytkownika dodatku. Tę funkcję określasz w polu onTriggerFunction pliku manifestu. Zaimplementujesz tę funkcję, aby przyjąć argument obiektu zdarzenia działania i zwracać pojedynczy obiekt Card lub tablicę obiektów Card.

Reguła kontekstowa uruchamia się dla danej wiadomości Gmaila, która wywołuje tę funkcję i przekazuje obiekt zdarzenia. Funkcje uruchamiające często używają identyfikatora wiadomości podanego przez ten obiekt zdarzenia, aby pobrać tekst wiadomości i inne szczegóły za pomocą usługi Gmail Apps Script. Funkcja aktywatora może na przykład wyodrębnić treść wiadomości przy użyciu 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 aktywatora może następnie użyć tych danych do wyodrębnienia informacji potrzebnych w interfejsie. Na przykład dodatek podsumowujący numery sprzedaży może zbierać dane dotyczące sprzedaży z treści wiadomości i porządkować je na karcie karty.

Funkcja aktywatora musi skompilować i zwrócić tablicę utworzonych obiektów Card. Poniższy przykład pozwala utworzyć dodatek z jedną 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];
  }