Strony główne to funkcja dodatków do Google Workspace, która umożliwia zdefiniowanie co najmniej 1 karty bez kontekstu. Karty bez kontekstu wyświetlają interfejs użytkownika, gdy użytkownik nie znajduje się w określonym kontekście, np. gdy przegląda skrzynkę odbiorczą Gmaila bez otwartej wiadomości lub wersji roboczej.
Strony główne umożliwiają wyświetlanie treści niezwiązanych z kontekstem, podobnie jak aplikacje Google w panelu bocznym szybkiego dostępu (Google Keep, Kalendarz Google i Lista zadań Google). Strony główne mogą też stanowić punkt wyjścia, gdy użytkownik po raz pierwszy otworzy dodatek. Są przydatne, gdy chcesz nauczyć nowych użytkowników, jak korzystać z dodatku.
Zdefiniuj stronę główną dodatku, określając ją w pliku manifestu projektu i wdrażając co najmniej 1 funkcję homepageTrigger (patrz Konfiguracja strony głównej). Jeśli dodatek rozszerza Google Chat, jego strona główna pojawia się na karcie Strona główna w bezpośredniej wiadomości 1:1 z aplikacją Google Chat i jest konfigurowana w konsoli Google Cloud zamiast w pliku manifestu (patrz Konfigurowanie strony głównej dla Google Chat).
Możesz mieć wiele stron głównych, po jednej dla każdej aplikacji hosta, którą rozszerza Twój dodatek. Możesz też zdefiniować jedną wspólną domyślną stronę główną, która będzie używana na hostach, na których nie określono niestandardowej strony głównej.
Strona główna dodatku wyświetla się w tych przypadkach:
- Gdy dodatek zostanie otwarty po raz pierwszy w aplikacji hosta (po autoryzacji) lub gdy użytkownik otworzy kartę Strona główna w bezpośredniej wiadomości 1:1 z Twoją aplikacją do obsługi czatu w Google Chat.
- Gdy użytkownik przełącza się z kontekstu kontekstowego na kontekst niekontekstowy, gdy dodatek jest otwarty. Na przykład z edytowania wydarzenia w Kalendarzu do głównego Kalendarza.
- Gdy użytkownik kliknie przycisk Wstecz wystarczającą liczbę razy, aby usunąć z wewnętrznych stosów co drugą kartę.
- Gdy interakcja z interfejsem w karcie niekontekstowej powoduje wywołanie funkcji
Navigation.popToRoot.
Zalecamy zaprojektowanie strony głównej. Jeśli nie zdefiniujesz żadnej karty, za każdym razem, gdy użytkownik przejdzie na stronę główną, będzie używana ogólna karta zawierająca nazwę dodatku.
Konfiguracja strony głównej
Dodatki do Google Workspace używają pola addOns.common.homepageTrigger do konfigurowania domyślnej strony głównej (niezależnej od kontekstu) dodatku w przypadku aplikacji hostujących w pliku manifestu dodatku:
{
"addOns": {
"common": {
"homepageTrigger": {
"runFunction": "myFunction",
"enabled": true
}
}
}
}
runFunction: nazwa funkcji Google Apps Script, którą platforma dodatków do Google Workspace wywołuje w celu renderowania kart dodatku na stronie głównej. Ta funkcja to funkcja aktywująca stronę główną. Ta funkcja musi tworzyć i zwracać tablicę obiektówCard, które składają się na interfejs strony głównej. Jeśli zwrócono więcej niż 1 kartę, aplikacja hosta wyświetla nagłówki kart na liście, z której użytkownik może wybrać kartę (patrz Zwracanie wielu kart).enabled: czy karty strony głównej powinny być włączone w tym zakresie. To pole jest opcjonalne, a jego wartość domyślna totrue. Ustawienie tej wartości nafalsepowoduje wyłączenie kart na stronie głównej na wszystkich hostach (chyba że zostanie to zastąpione w przypadku danego hosta; patrz konfiguracja specyficzna dla hosta).
Aby host mógł korzystać ze wspólnej strony głównej, w manifeście dodatku muszą być obecne zarówno addOns.common.homepageTrigger, jak i zasób najwyższego poziomu hosta. Jeśli na przykład element addOns.gmail nie występuje w manifeście, dodatek jest wyłączony w Gmailu i nie wyświetla strony głównej ani innych funkcji w tym hoście.
Oprócz wspólnej konfiguracji w konfiguracji każdej aplikacji hosta dostępne są identycznie skonstruowane zastąpienia dla poszczególnych hostów w przypadku addOns.gmail.homepageTrigger, addOns.calendar.homepageTrigger i innych wyzwalaczy specyficznych dla hosta.
Poniższy przykład pokazuje plik manifestu, w którym zdefiniowano wspólny wyzwalacz strony głównej, ale został on zastąpiony funkcjami niestandardowymi w przypadku Kalendarza i Dysku oraz wyłączony w przypadku Gmaila. W tej konfiguracji wspólna funkcja buildHomePage nigdy nie jest wykonywana, ponieważ jest zastępowana lub host jest wyłączony.
{
...
"addOns": {
...
"common": {
"homepageTrigger": { "runFunction": "buildHomePage" }
},
"calendar": {
"homepageTrigger": { "runFunction": "buildCalendarHomepage" }
},
"drive": {
"homepageTrigger": { "runFunction": "buildDriveHomepage" }
},
"gmail": {
"homepageTrigger": { "enabled": false }
},
...
}
}
Poniższy fragment pliku manifestu jest odpowiednikiem poprzedniego przykładu, mimo że pominięto domyślny element homepageTrigger i konfigurację Gmaila:
{
"addOns": {
"common": {},
"calendar": {
"homepageTrigger": { "runFunction": "myCalendarFunction" }
},
"drive": {
"homepageTrigger": { "runFunction": "myDriveFunction" }
},
"gmail": {},
...
}
}
Żadna z sekcji homepageTrigger nie jest wymagana. Interfejs dodatku w produkcie hostującym zależy od obecności odpowiedniego pola manifestu i tego, czy jest powiązany z homepageTrigger. Poniższy przykład pokazuje, które funkcje wyzwalacza dodatku są wykonywane w celu utworzenia interfejsu strony głównej dla różnych konfiguracji pliku manifestu:
Konfigurowanie strony głównej Google Chat
W przeciwieństwie do innych aplikacji hostujących Google Workspace dodatki rozszerzające Chat nie wyświetlają strony głównej w panelu szybkiego dostępu po prawej stronie i nie używają addOns.common.homepageTrigger w pliku manifestu.
Zamiast tego Google Chat wyświetla Twoją stronę główną jako kartę na karcie Strona główna w wiadomości bezpośredniej 1:1 z aplikacją Google Chat.
Aby włączyć i skonfigurować aktywator strony głównej aplikacji dla dodatku do Google Chat w konsoli Google Cloud:
W konsoli Google Cloud otwórz Menu > Interfejsy API i usługi > Włączone interfejsy API i usługi > Google Chat API > Konfiguracja.
W sekcji Funkcje interaktywne sprawdź, czy opcja Włącz funkcje interaktywne jest włączona, a następnie zaznacz pole wyboru Strona główna aplikacji pomocy.
W sekcji Ustawienia połączenia > Wyzwalacze w polu Strona główna aplikacji określ moduł obsługi strony głównej aplikacji na podstawie architektury dodatku:
- HTTP wpisz adres URL punktu końcowego HTTPS, który obsługuje żądania strony głównej aplikacji (lub pozostaw to pole puste, aby wszystkie zdarzenia były odbierane przez wspólny adres URL punktu końcowego HTTP).
- Google Apps Script: wpisz nazwę wywołania zwrotnego Google Apps Script, które tworzy i zwraca kartę strony głównej (domyślnie
onAppHome).
Kliknij Zapisz.
Gdy użytkownik otworzy kartę Główna na czacie z aplikacją do Google Chat, Google Chat wyśle do punktu końcowego lub funkcji zdarzenie wywołujące Strona aplikacji. Aby wyrenderować stronę główną, zwróć obiekt
RenderActions
z działaniem nawigacyjnym pushCard (lub użyj updateCard podczas aktualizowania
strony głównej w odpowiedzi na kliknięcie przycisku na karcie strony głównej):
HTTP
{ "action": { "navigations": [ { "pushCard": { "header": { "title": "Welcome to App Home" }, "sections": [ { "widgets": [ { "textParagraph": { "text": "Manage your settings and view your dashboard here." } } ] } ] } } ] } }
Google Apps Script
function onAppHome(event) { const card = CardService.newCardBuilder() .setHeader( CardService.newCardHeader().setTitle('Welcome to App Home')) .addSection( CardService.newCardSection().addWidget( CardService.newTextParagraph().setText( 'Manage your settings and view your dashboard here.'))) .build(); return CardService.newActionResponseBuilder() .setNavigation(CardService.newNavigation().pushCard(card)) .build(); }
Więcej informacji o obsłudze aktywatorów Google Chat i zwracaniu działań znajdziesz w artykule Odbieranie interakcji użytkownika i odpowiadanie na nie.
Obiekty zdarzeń na stronie głównej
Po wywołaniu funkcji wyzwalacza strony głównej (runFunction) lub punktu końcowego strony głównej aplikacji, opisanych wcześniej, przekazywany jest obiekt zdarzenia zawierający dane z kontekstu wywołania.
Obiekty zdarzeń na stronie głównej nie zawierają informacji o widżecie ani informacji kontekstowych. Przekazywane informacje obejmują te pola obiektu zdarzenia wspólnego:
commonEventObject.clientPlatformcommonEventObject.hostAppcommonEventObject.userLocaleicommonEventObject.userTimezone(informacje o ograniczeniach znajdziesz w artykule Uzyskiwanie dostępu do regionu i strefy czasowej użytkownika).
W Chat obiekt zdarzenia Strona aplikacji zawiera też pole chat
z informacjami o użytkowniku i czasie interakcji:
chat.user: użytkownik Google Chat, który otworzył kartę Główna.chat.eventTime: sygnatura czasowa otwarcia przez użytkownika karty Strona główna.
Więcej informacji znajdziesz w sekcji Obiekt zdarzenia.
Inne karty niekontekstowe
Interfejs dodatku może zawierać dodatkowe karty niekontekstowe, które nie są stronami głównymi. Na przykład na stronie głównej może być przycisk, który otwiera kartę „Ustawienia”, aby dostosować ustawienia dodatku (takie ustawienia są zwykle niezależne od kontekstu).
Karty niekontekstowe są tworzone jak inne karty. Jedyna różnica polega na tym, jakie działanie lub zdarzenie generuje i wyświetla kartę. Więcej informacji o tworzeniu przejść między kartami znajdziesz w sekcji Metody nawigacji.