Rozszerzenie interfejsu wiadomości

Dodatki Google Workspace, które rozszerzają Gmaila, mogą udostępniać interfejs użytkownika podczas czytania wiadomości. Dzięki temu dodatki Google Workspace mogą automatyzować zadania związane z treścią wiadomości, takie jak wyświetlanie, pobieranie lub wysyłanie dodatkowych informacji związanych z wiadomością.

Otwieranie interfejsu użytkownika wiadomości w dodatku

Istnieją 2 sposoby wyświetlania interfejsu wiadomości dodatku. Pierwszym sposobem jest otwarcie wiadomości, gdy dodatek jest już otwarty (np. podczas wyświetlania strony głównej dodatku w oknie skrzynki odbiorczej Gmaila). Drugim sposobem jest uruchomienie dodatku podczas wyświetlania wiadomości.

W obu przypadkach dodatek wykona odpowiednią funkcję kontekstowego aktywatora zdefiniowaną w pliku manifestu dodatku. Wyzwalacz jest też uruchamiany, gdy użytkownik przełączy się na inną wiadomość, a inne rozszerzenie jest nadal otwarte. Funkcja wywołania kontekstowego tworzy interfejs wiadomości, który Gmail wyświetla użytkownikowi.

Tworzenie rozszerzenia wiadomości

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

1. Dodaj odpowiednie pola do pliku manifestu projektu skryptu dodatku, w tym zakresy wymagane do obsługi funkcji wiadomości. Pamiętaj, aby dodać do pliku manifestu pole wyzwalacza warunkowego z wartością unconditional{}.
2. Wdrożyć funkcję kontekstowego aktywatora, 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.

Czynniki uruchamiające w kontekście

Aby ułatwić użytkownikom czytanie wiadomości, dodatki Google Workspace mogą w swoich plikach manifestu zdefiniować wyzwalacz kontekstowy. Gdy użytkownik otworzy wiadomość w Gmailu (z otwartym dodatkiem), która spełnia kryteria reguły*, reguła zostanie uruchomiona. Wyzwoliony przez nie powoduje wykonanie funkcji kontekstowego wyzwalacza, która tworzy interfejs użytkownika dodatku i zwraca go do wyświetlenia w Gmailu. W tym momencie użytkownik może zacząć z niego korzystać.

Wyzwalacze kontekstowe są definiowane w pliku manifestu projektu dodatku. Definicja reguły określa Gmailowi, jaką funkcję reguły należy wykonać i w jakich warunkach. Ten fragment pliku manifestu powoduje uruchomienie bezwarunkowego reguły, która wywołuje funkcję reguły onGmailMessageOpen() po otwarciu wiadomości:

{
  ...
  "addOns": {

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

Funkcja kontekstowego wyzwalacza

Każdy kontekstualny wyzwalacz musi mieć odpowiadającą mu funkcję wyzwalacza, która tworzy interfejs użytkownika dodatku. Określasz tę funkcję w polu onTriggerFunction w pliku manifestu. Funkcję tę wdrażasz, aby zaakceptować argument obiektu zdarzenia akcji i zwrócić obiekt Card lub tablicę obiektów Card.

Gdy w przypadku danej wiadomości w Gmailu zostanie uruchomiony kontekstowy reguła, wywołuje ona tę funkcję i przekazuje jej obiekt zdarzenia działania. Funkcje reguły często używają identyfikatora wiadomości podanego przez to zdarzenie, aby uzyskać tekst wiadomości i inne szczegóły za pomocą usługi Gmail w Apps Script. Funkcja reguły 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 reguły może następnie działać na podstawie tych danych, wyodrębniając informacje potrzebne do interfejsu. Na przykład dodatek podsumowujący liczby sprzedaży może zbierać dane o sprzedaży z treści wiadomości i porządkować je w celu wyświetlania na karcie.

Funkcja aktywatora musi tworzyć i zwracać tablicę obiektów Card. Na przykład poniższy kod tworzy dodatek z jedną kartą, na której znajduje się tylko temat i nadawca 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];
  }