Obiekty zdarzenia

Ta strona przedstawia strukturę obiektów zdarzeń dodatków do Google Workspace.

Obiekty zdarzeń to struktury JSON, które są automatycznie konstruowane i przekazywane jako parametry w celu aktywowania funkcji lub wywołań zwrotnych, gdy użytkownik wejdzie w interakcję z dodatkiem. Obiekty zdarzeń zawierają informacje o aplikacji hosta po stronie klienta oraz aktualny kontekst funkcji wywołania zwrotnego dodatku po stronie serwera.

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

• Reguły dotyczące strony głównej. Każda zdefiniowana przez Ciebie funkcja homepageTrigger jest automatycznie przekazywana po uruchomieniu funkcji aktywatora strony głównej. Możesz użyć tego obiektu w funkcji aktywatora strony głównej, aby zidentyfikować aktywną aplikację hosta, platformę klienta, język użytkownika i inne informacje.

  Obiekty zdarzeń tworzone po uruchomieniu aktywatora strony głównej nie zawierają wszystkich pól zawartych w pozostałych 2 przypadkach. Pola dotyczące widżetów i informacji kontekstowych są pomijane.

• Reguły kontekstowe. Każda aplikacja hostująca udostępnia inny zestaw kontekstowych aktywatorów, które uruchamiają się, gdy użytkownik wprowadza określony kontekst. Na przykład:

  • Gmail udostępnia aktywator kontekstowy, gdy użytkownik otworzy wiadomość, a drugiego, gdy użytkownik utworzy wiadomość.
  • Kalendarz Google udostępnia wyzwalacz kontekstowy, gdy użytkownik otworzy wydarzenie.
  • Dysk Google jest uruchamiany kontekstowo, gdy użytkownik wybierze pliki na Dysku.

  Po uruchomieniu aktywatora kontekstowego aplikacja hosta wywołuje odpowiedni element runFunction wymieniony w pliku manifestu dodatku, przekazując go jako parametr obiekt zdarzenia. Obiekty zdarzeń utworzone po uruchomieniu reguł kontekstowych zawierają wszystkie pola uwzględnione w obiektach zdarzeń reguły na stronie głównej oraz pola zawierające informacje kontekstowe.

• Działania widżetu. Obiekty zdarzeń służą też do generowania interakcji z widżetami przy użyciu tego samego modelu czynności, z którego korzystają 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. Jednak w dodatkach do Google Workspace obiekty zdarzeń czynności zawierają jeszcze więcej informacji, na podstawie których funkcja wywołania zwrotnego może działać.

  Obiekty zdarzeń utworzone w wyniku działań widżetów zawierają wszystkie pola uwzględnione w kontekstowych obiektach zdarzeń aktywujących oraz pola z informacjami o widżetach.

• Podgląd reguł połączenia kont. W Dokumentach, Arkuszach i Prezentacjach Google możesz skonfigurować podgląd linków w usługach innych firm na podstawie określonych wzorców adresów URL. Gdy użytkownicy wchodzą w interakcję z linkiem zgodnym ze wzorcem, uruchamia się linkPreviewTriggers, a obiekt zdarzenia zawierający link jest przekazywany do funkcji wywołania zwrotnego aktywatora. Dodatek może używać tego obiektu zdarzenia do utworzenia elementu inteligentnego i karty wyświetlającej informacje o linku w aplikacji hostującej. Możesz też utworzyć działania widżetów, które umożliwią użytkownikom interakcję z kartą podglądu i jej zawartością.

Struktura obiektu zdarzenia

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

Aby zapewnić zgodność wsteczną, obiekty zdarzeń dodatków do Google Workspace zawierają też wszystkie oryginalne pola używane w obiektach zdarzeń działań dodatku w Gmailu. Te pola są wymienione w tabeli poniżej w sekcji „Pola oryginalnego dodatku w Gmailu”. Informacje w tych polach są odtworzone w nowej strukturze obiektów.

Typowy obiekt zdarzenia

Typowy obiekt zdarzenia to część ogólnego obiektu zdarzenia, która przekazuje do dodatku ogólne, niezależne od hosta informacje z klienta użytkownika. Informacje te obejmują szczegóły, takie jak język użytkownika, aplikacja hosta i platforma.

Oprócz strony głównej i reguł kontekstowych dodatki tworzą i przekazują obiekty zdarzeń do funkcji wywołania zwrotnego działań, 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 w kliencie użytkownika. Dodatek może na przykład zlokalizować tekst wpisany przez użytkownika w widżecie TextInput w obiekcie eventObject.commentEventObject.formInputs.

Dane wejściowe formularza selektora daty i godziny

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

Obiekt wydarzenia w kalendarzu

Obiekt wydarzenia Calendar to część ogólnego obiektu wydarzenia, która zawiera informacje o kalendarzu użytkownika i wydarzeniach w kalendarzu. Jest on widoczny w obiekcie wydarzenia tylko wtedy, gdy aplikacją hostującą jest Kalendarz Google.

W tabeli poniżej znajdziesz pola występujące w polu calendarEventObject obiektu zdarzenia. Pola oznaczone jako Dane wygenerowane przez użytkowników występują w obiekcie zdarzenia tylko wtedy, gdy dane te znajdują się w zdarzeniu w Kalendarzu, a dodatek ustawi w addOns.calendar.currentEventAccess pliku manifestu pole addOns.calendar.currentEventAccess pliku manifestu na READ lub READ_WRITE.

Uczestnik

Obiekty uczestników przenoszą informacje o poszczególnych uczestnikach do wydarzeń w Kalendarzu Google. Informacje te znajdują się w obiekcie zdarzenia tylko wtedy, gdy dane te znajdują się w wydarzeniu z Kalendarza, a dodatek ustawi swój pole addOns.calendar.currentEventAccess manifest na READ lub READ_WRITE.

Dane konferencji

Obiekty danych konferencji zawierają informacje o konferencjach dołączone do wydarzeń w Kalendarzu Google. Rozwiązania Google do prowadzenia rozmów wideo, np. Google Meet, lub narzędzia do obsługi rozmów wideo z innymi firmami. Te informacje znajdują się w obiekcie zdarzenia tylko wtedy, gdy dane te znajdują się w wydarzeniu z Kalendarza, a dodatek ustawi swój pole addOns.calendar.currentEventAccess manifest na READ lub READ_WRITE.

Punkt wejścia

Obiekty punktu wejścia zawierają informacje o istniejących sposobach dostępu do danej konferencji, np. za pomocą telefonu lub rozmowy wideo. Informacje te znajdują się w obiekcie zdarzenia tylko wtedy, gdy dane te znajdują się w wydarzeniu z Kalendarza, a dodatek ustawi swój pole addOns.calendar.currentEventAccess manifest na READ lub READ_WRITE.

Obiekt zdarzenia na Dysku

Obiekt zdarzenia Dysku to część ogólnego obiektu zdarzenia, która zawiera informacje o Dysku Google użytkownika i jego zawartości. Jest on widoczny w obiekcie zdarzenia tylko wtedy, gdy aplikacją hostującą jest Dysk Google.

Element na Dysku

Obiekty elementów na Dysku zawierają informacje o konkretnych elementach na Dysku, takich jak pliki czy foldery.

Obiekt zdarzenia Gmaila

Obiekt zdarzenia Gmaila to część ogólnego obiektu zdarzenia, która przekazuje informacje o wiadomościach z Gmaila użytkownika. Występuje w obiekcie zdarzenia tylko wtedy, gdy hostem jest Gmail.

Obiekt zdarzenia Dokumentów

Obiekt zdarzenia Dokumentów to część obiektu ogólnego zdarzenia, która przekazuje informacje o dokumencie użytkownika i jego zawartości. Występuje on w obiekcie zdarzenia tylko wtedy, gdy aplikacja hostująca jest Dokumentami Google.

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

Obiekt zdarzenia Arkuszy

Obiekt zdarzeń Arkuszy to część ogólnego obiektu zdarzenia, który przekazuje informacje o dokumencie użytkownika i jego zawartości. Występuje on w obiekcie zdarzenia tylko wtedy, gdy aplikacją hostującą są Arkusze Google.

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

Obiekt zdarzenia w Prezentacjach

Obiekt zdarzenia w Prezentacjach to część ogólnego obiektu zdarzenia, który przekazuje informacje o dokumencie użytkownika i jego zawartości. Występuje on w obiekcie zdarzenia tylko wtedy, gdy aplikacja hostującą to Prezentacje Google.

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