Obiekty zdarzenia

Ta strona przedstawia 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 wywołania lub wywołania zwrotnego, gdy użytkownik wejdzie w interakcję z dodatkiem. Obiekty zdarzeń przekazują do funkcji wywołania zwrotnego po stronie serwera dodatku informacje o aplikacji goszczącej i bieżącym kontekście po stronie klienta.

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

• Wyzwalacze strony głównej. Każda zdefiniowana przez Ciebie funkcja homepageTrigger jest automatycznie przekazywana do obiektu zdarzenia, gdy uruchamia się funkcja reguły na stronie głównej. Możesz używać tego obiektu w funkcji reguły strony głównej, aby zidentyfikować aktywną aplikację hosta, platformę klienta, lokalizację użytkownika i inne informacje.

  Obiekty zdarzeń utworzone po wywołaniu przez stronę główną nie zawierają wszystkich pól uwzględnionych w 2 pozostałych przypadkach. Nie uwzględniono pól dotyczących widżetów i informacji kontekstowych.

• Reguły kierowania kontekstowego. Każda aplikacja hosta udostępnia inny zestaw wyzwalaczy kontekstowych, które działają, gdy użytkownik wejdzie w określony kontekst. Na przykład:

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

  Gdy zostanie uruchomiony kontekstowy reguła, aplikacja hosta wywołuje odpowiednią runFunction wymienioną w pliku manifestu dodatku, przekazując jej obiekt zdarzenia jako parametr. Obiekty zdarzeń tworzone podczas aktywacji przez wyzwalacze kontekstowe zawierają wszystkie pola zawarte w obiektach zdarzeń wyzwalacza strony głównej oraz pola zawierające informacje kontekstowe.

• Działania widżetu. Obiekty zdarzeń służą też do zapewnienia interakcji z widżetem, przy użyciu tego samego modelu działania, którego używają dodatki do Gmaila. Dodatki Google Workspace korzystają z tych samych funkcji obsługi widżetów, obiektów Action i odpowiedzi na działania. Jednak w przypadku dodatków Google Workspace obiekty zdarzeń akcji zawierają jeszcze więcej informacji, z których może korzystać funkcja wywołania zwrotnego.

  Obiekty zdarzeń utworzone w wyniku działań widżetu zawierają wszystkie pola zawarte w obiektach zdarzeń wyzwalacza kontekstowego oraz pola zawierające informacje o widżecie.

• Reguły wywoływania linku do podglądu. W Dokumentach, Arkuszach i Prezentacjach Google możesz konfigurować podgląd linków do usług innych firm na podstawie określonych wzorów adresów URL. Gdy użytkownicy wejdą w interakcję z linkiem, który spełnia wzór, uruchamia się zdarzenie linkPreviewTriggers, a do funkcji wywołania zwrotnego reguły przekazywany jest obiekt zdarzenia zawierający link. Twój dodatek może używać tego obiektu zdarzenia do tworzenia elementu inteligentnego i karty, które wyświetlają informacje o linku w aplikacji gospodarza. Możesz też tworzyć działania widżetu, aby umożliwić użytkownikom interakcję z kartą podglądu i jej zawartością.

• Reguły aplikacji Google Chat (wersja dla programistów). W Google Chat Twój dodatek jest widoczny dla użytkowników jako aplikacja Google Chat, z którą mogą wchodzić w interakcje, dodając ją do pokoi, wysyłając wiadomości, używając poleceń po ukośniku itp. Aby tworzyć funkcje interaktywne, skonfiguruj i używaj różnych komend aplikacji Google Chat. Każdy taki element wysyła inny ładunek obiektu zdarzenia, który pomaga przetwarzać lub odpowiadać na różne typy interakcji.

Struktura obiektu zdarzenia

Tabela poniżej opisuje strukturę najwyższego poziomu obiektów zdarzeń wtyczek Google Workspace. Struktura obiektu zdarzenia zawiera pole najwyższego poziomu commonEventObject z informacjami niezależnymi od hosta. Każdy obiekt zdarzenia może też zawierać jedno z tych pól najwyższego poziomu, które zależy od aktywnej aplikacji hosta: gmailEventObject, calendarEventObject lub driveEventObject.

Ze względu na zgodność wsteczną obiekty zdarzeń w dodatkach Google Workspace zawierają też wszystkie oryginalne pola używane w obiektach zdarzeń działania w dodatkach do Gmaila. Te pola znajdziesz w tabeli poniżej w sekcji „Pierwotne pola dodatku Gmaila”. Informacje z tych pól są powielane w nowej strukturze obiektu.

Obiekt wspólnego zdarzenia

Obiekt wspólnego zdarzenia to część ogólnego obiektu zdarzenia, który zawiera ogólne informacje niezależne od hosta i przesyła je do dodatku z klienta użytkownika. Te informacje obejmują takie dane jak lokalizacja użytkownika, aplikacja hosta i platforma.

Oprócz reguł dotyczących strony głównej i reguł kontekstowych dodatki tworzą i przekazują obiekty zdarzeń do funkcji wywołania działania, gdy użytkownik wchodzi w interakcję z widżetami. Funkcja wywołania zwrotnego dodatku może wysyłać zapytanie do wspólnego obiektu zdarzenia, aby określić zawartość otwartych widżetów w kliencie użytkownika. Twój dodatek może na przykład znaleźć 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 akcji mogą otrzymywać bieżące wartości widżetu w polu commonEventObject.formInputs. Dotyczy to wybranych przez użytkownika wartości daty lub czasu w widżetach selektora daty lub czasu. Struktura informacji różni się jednak 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 tabeli poniżej:

Obiekt zdarzenia w kalendarzu

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

W tabeli poniżej znajdziesz listę pól w polu calendarEventObject obiektu zdarzenia. Pola oznaczone jako Dane utworzone przez użytkownika są obecne w obiekcie zdarzenia, jeśli i tylko jeśli dane są obecne w zdarzeniu w Kalendarzu, a dodatek ustawia pole addOns.calendar.currentEventAccess manifest na wartość READ lub READ_WRITE.

Uczestnik

Obiekty uczestników zawierają informacje o poszczególnych uczestnikach wydarzeń w Kalendarzu Google. Te informacje są obecne w obiekcie zdarzenia, jeśli i tylko jeśli dane są obecne w zdarzeniu w kalendarzu, a dodatek ustawia pole addOns.calendar.currentEventAccess manifest na wartość READ lub READ_WRITE.

Dane konferencji

Obiekty danych konferencji zawierają informacje o konferencjach dołączonych do wydarzeń w Kalendarzu Google. Mogą to być rozwiązania do rozmów wideo Google, takie jak Google Meet, lub rozmowy wideo z udziałem innych firm. Te informacje są obecne w obiekcie zdarzenia, jeśli i tylko jeśli dane są obecne w wydarzeniu w kalendarzu, a dodatek ustawia pole addOns.calendar.currentEventAccess manifest na wartość READ lub READ_WRITE.

Punkt wejścia

Obiekty punktów dostępu zawierają informacje o ustalonych sposobach dostępu do danej konferencji, takich jak telefon lub wideo. Te informacje są obecne w obiekcie zdarzenia, jeśli i tylko jeśli dane są obecne w wydarzeniu w Kalendarzu, a dodatek ustawia pole addOns.calendar.currentEventAccess manifest na READ lub READ_WRITE.

Obiekt zdarzenia na Dysku

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

Element na Dysku

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

Obiekt zdarzenia Gmaila

Obiekt zdarzenia Gmail to część ogólnego obiektu zdarzenia, który zawiera informacje o wiadomościach Gmaila użytkownika. Jest on obecny tylko w obiekcie zdarzenia, jeśli aplikacją hosta jest Gmail.

Obiekt zdarzenia Dokumenty

Obiekt zdarzenia Docs to część ogólnego obiektu zdarzenia, który zawiera informacje o dokumencie użytkownika i jego zawartości. Jest on obecny w obiekcie event tylko wtedy, gdy aplikacją hostującą jest Dokumenty Google.

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

Obiekt zdarzenia Arkuszy

Obiekt zdarzenia w Sheets to część ogólnego obiektu zdarzenia, który zawiera informacje o dokumencie użytkownika i jego zawartości. Jest on obecny tylko w obiekcie zdarzenia, jeśli aplikacją hostującą jest Arkusze Google.

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

Obiekt zdarzenia Slides

Obiekt zdarzenia Slides to część ogólnego obiektu zdarzenia, który zawiera informacje o dokumencie użytkownika i jego zawartości. Jest on obecny tylko w obiekcie zdarzenia, jeśli aplikacja hostująca to Prezentacje Google.

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