Rozszerzenie interfejsu wiadomości

Dodatki do Google Workspace, które rozszerzają Gmaila, mogą udostępniać interfejs użytkownika, gdy użytkownik czyta wiadomości. Umożliwia to dodatkom Google Workspace automatyzowanie zadań, które reagują na treść wiadomości, takich jak wyświetlanie, pobieranie lub wysyłanie dodatkowych informacji związanych z wiadomością.

Dostęp do interfejsu wiadomości dodatku

Interfejs wiadomości dodatku możesz wyświetlić na 2 sposoby. Pierwszy sposób polega na otwarciu wiadomości, gdy dodatek jest już otwarty (np. 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 wykonuje odpowiednią funkcję aktywatora kontekstowego zdefiniowaną w manifeście dodatku. Wywoływacz jest też uruchamiany, gdy użytkownik przełączy się na inną wiadomość, a dodatek jest nadal otwarty. Funkcja wywołująca kontekstowo tworzy interfejs wiadomości, który Gmail wyświetla użytkownikowi.

Tworzenie dodatku do wiadomości

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

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

Aktywatory kontekstowe

Aby pomóc użytkownikom w czytaniu wiadomości, dodatki do Google Workspace mogą zdefiniować w swoich plikach manifestu wyzwalacz kontekstowy. Gdy użytkownik otworzy wiadomość w Gmailu (z otwartym dodatkiem), która spełnia kryteria wyzwalacza*, wyzwalacz zostanie uruchomiony. Wywołany wyzwalacz wykonuje funkcję wyzwalacza kontekstowego, która tworzy interfejs użytkownika dodatku i zwraca go do Gmaila w celu wyświetlenia. W tym momencie użytkownik może zacząć z nią wchodzić w interakcję.

Wywołania kontekstowe są zdefiniowane w manifeście projektu dodatku. Definicja wyzwalacza informuje Gmaila, którą funkcję wyzwalacza należy uruchomić w jakich warunkach. Na przykład ten fragment pliku manifestu ustawia bezwarunkową regułę, która wywołuje funkcję reguły onGmailMessageOpen() po otwarciu wiadomości:

{
  ...
  "addOns": {

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

Funkcja aktywatora kontekstowego

Każdy wyzwalacz kontekstowy musi mieć odpowiednią funkcję wyzwalacza, która tworzy interfejs użytkownika dodatku. Tę funkcję określa się w polu onTriggerFunction pliku manifestu. Implementujesz tę funkcję, aby przyjmowała argument obiektu zdarzenia działania i zwracała pojedynczy obiekt Card lub tablicę obiektów Card.

Gdy w przypadku danej wiadomości w Gmailu zostanie uruchomiony wyzwalacz kontekstowy, wywoła on tę funkcję i przekaże jej obiekt zdarzenia działania. Funkcje wyzwalane często używają identyfikatora wiadomości podanego przez ten obiekt zdarzenia, aby uzyskać tekst wiadomości i inne szczegóły za pomocą usługi Gmail Apps Script. Na przykład funkcja wyzwalająca może wyodrębniać 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 wyzwalająca może następnie przetwarzać te dane, wyodrębniając informacje potrzebne do interfejsu. Na przykład dodatek, który podsumowuje dane sprzedaży, może zbierać liczby sprzedaży z treści wiadomości i porządkować je w celu wyświetlenia na karcie.

Funkcja aktywatora musi tworzyć i zwracać tablicę utworzonych obiektówCard. Na przykład poniższy kod tworzy 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];
  }