Obiekty zdarzenia

Na tej stronie opisujemy strukturę obiektów zdarzeń dodatków do Google Workspace.

Obiekty zdarzeń to struktury JSON, które są automatycznie tworzone i przekazywane jako parametry do funkcji aktywatora lub wywołania zwrotnego, gdy użytkownik wchodzi w interakcję z dodatkiem. Obiekty zdarzeń zawierają informacje po stronie klienta o aplikacji hosta i bieżącym kontekście, które są przekazywane do funkcji wywołania zwrotnego po stronie serwera dodatku.

Dodatki do Google Workspace używają obiektów zdarzeń w tych miejscach:

• Reguły strony głównej Każda zdefiniowana funkcja homepageTrigger automatycznie otrzymuje obiekt zdarzenia, gdy uruchamia się funkcja reguły strony głównej. Możesz użyć tego obiektu w funkcji wywołującej stronę główną, aby zidentyfikować aktywną aplikację hosta, platformę klienta, region użytkownika i inne informacje.

  Obiekty zdarzeń tworzone po uruchomieniu wyzwalaczy strony głównej nie zawierają wszystkich pól, które są uwzględniane w innych przypadkach. Pomijane są pola dotyczące widżetów i informacji kontekstowych.

• Reguły kontekstowe Każda aplikacja hostująca udostępnia inny zestaw wyzwalaczy kontekstowych, które są aktywowane, gdy użytkownik znajdzie się w określonym kontekście:

  • Gdy użytkownik:
    • otwiera wiadomość
    • tworzy wiadomość,
    • otwiera wydarzenie.
  • Dysk Google udostępnia wyzwalacz kontekstowy, gdy użytkownik wybiera pliki na Dysku.

  Gdy zostanie wywołany wyzwalacz kontekstowy, aplikacja hostująca wywołuje odpowiednią funkcję runFunction wymienioną w pliku manifestu dodatku, przekazując jej obiekt zdarzenia jako parametr. Obiekty zdarzeń tworzone po uruchomieniu reguł kontekstowych zawierają wszystkie pola uwzględnione w obiektach zdarzeń reguł na stronie głównej oraz pola zawierające informacje kontekstowe.

• Działania widżetu. Obiekty zdarzeń zapewniają interaktywność widżetu, korzystając z tego samego modelu działania, którego używają dodatki do Gmaila. Dodatki do Google Workspace korzystają z tych samych funkcji obsługi widżetów, obiektów Action i odpowiedzi na działania. W dodatkach do Google Workspace obiekty zdarzeń działania zawierają więcej informacji, na podstawie których funkcja wywołania zwrotnego może podejmować działania.

  Obiekty zdarzeń utworzone na podstawie działań widżetu zawierają wszystkie pola uwzględnione w obiektach zdarzeń wyzwalacza kontekstowego oraz pola zawierające informacje o widżecie.

• Reguły linku do podglądu. W Dokumentach Google, Arkuszach i Prezentacjach możesz skonfigurować podgląd linków do usług innych firm na podstawie określonych wzorców adresów URL. Gdy użytkownicy wchodzą w interakcję z linkiem, który pasuje do wzorca, uruchamia się linkPreviewTriggers, a do funkcji wywołania zwrotnego wyzwalacza przekazywany jest obiekt zdarzenia zawierający link. Dodatek może używać tego obiektu zdarzenia do tworzenia elementu inteligentnego i karty, które wyświetlają informacje o linku w aplikacji hosta. Możesz też tworzyć działania widżetu, aby użytkownicy mogli wchodzić w interakcję z kartą podglądu i jej zawartością.

• Triggery aplikacji Google Chat. W Google Chat dodatek jest widoczny dla użytkowników jako aplikacja Google Chat, z którą mogą oni wchodzić w interakcje, dodając ją do pokoi, wysyłając wiadomości, używając poleceń ze znakiem ukośnika itp. Aby tworzyć funkcje interaktywne, musisz skonfigurować i używać różnych aktywatorów aplikacji do obsługi czatu. Każdy wyzwalacz wysyła inny ładunek obiektu zdarzenia, który pomaga przetwarzać każdy rodzaj interakcji lub na niego reagować.

Struktura obiektu zdarzenia

W tabeli poniżej opisano strukturę najwyższego poziomu obiektów zdarzeń dodatków do Google Workspace. Struktura zawiera pole najwyższego poziomu commonEventObject dla informacji niezależnych od hosta. Każdy obiekt zdarzenia może też mieć jedno z tych pól najwyższego poziomu specyficznych dla hosta, które są określane przez aktywną aplikację hosta: gmailEventObject, calendarEventObject lub driveEventObject.

Aby zapewnić zgodność wsteczną, obiekty zdarzeń dodatków Google Workspace zawierają oryginalne pola używane w obiektach zdarzeń działań dodatków w Gmailu. Te pola znajdują się w sekcji „Pola dodatku do oryginalnej wersji Gmaila” i nie są częścią commonEventObject.

Pola oryginalnego dodatku w Gmailu są przestarzałe. Podczas tworzenia lub przenoszenia dodatku do Google Workspace używaj nowszej struktury obiektu zdarzenia. Te pola mogą zostać usunięte w przyszłej aktualizacji.

Obiekt zdarzenia wspólnego

Obiekt zdarzenia wspólnego to część ogólnego obiektu zdarzenia, która zawiera ogólne, niezależne od hosta informacje przekazywane do dodatku z klienta użytkownika. Te informacje obejmują szczegóły takie jak język użytkownika, aplikacja hosta i platforma.

Oprócz strony głównej i wyzwalaczy kontekstowych dodatki tworzą i przekazują obiekty zdarzeń do funkcji zwrotnych działania, gdy użytkownik wchodzi w interakcję z widżetami. Funkcja wywołania zwrotnego dodatku może wysyłać zapytania do wspólnego obiektu zdarzenia, aby określić zawartość otwartych widżetów na urządzeniu klienta użytkownika. Na przykład dodatek może znaleźć tekst wpisany przez użytkownika w widżecie TextInput w obiekcie eventObject.commentEventObject.formInputs.

Pola formularza selektora daty i godziny

Funkcje wywołania zwrotnego działania mogą otrzymywać bieżące wartości widżetu w polu commonEventObject.formInputs. Obejmuje to wybrane przez użytkownika wartości daty lub czasu w widżetach selektora daty lub czasu. Struktura informacji różni się w zależności od tego, czy widżet został skonfigurowany jako selektor daty i godziny, selektor tylko daty czy selektor tylko godziny. Różnice strukturalne zostały opisane w tej tabeli:

Obiekt zdarzenia czatu

Obiekt zdarzenia w Google Chat to część ogólnego obiektu zdarzenia, która zawiera informacje o interakcjach użytkownika z aplikacją do obsługi czatu. Jest on obecny w obiekcie zdarzenia tylko wtedy, gdy dodatek rozszerza Google Chat.

Ładunek

W zależności od typu interakcji z aplikacją do obsługi czatu zdarzenie zawiera ładunek z co najmniej 1 zasobem interfejsu Chat API.

"docs" : {
  "matchedUrl" : {
      "url" : "https://www.example.com/12345"
  }
}
        

"sheets" : {
  "matchedUrl" : {
      "url" : "https://www.example.com/12345"
  }
}
        

"slides" : {
  "matchedUrl" : {
      "url" : "https://www.example.com/12345"
  }
}