Le home page sono una funzionalità dei componenti aggiuntivi Google Workspace che consente di definire una o più schede non contestuali. Le schede non contestuali mostrano un'interfaccia utente quando l'utente si trova al di fuori di un contesto specifico, ad esempio quando visualizza la posta in arrivo di Gmail senza un messaggio o una bozza aperti.
Le home page ti consentono di mostrare contenuti non contestuali, simili alle app Google nel riquadro laterale di accesso rapido (Google Keep, Google Calendar e Google Tasks). Le home page possono anche fornire un punto di partenza iniziale quando un utente apre per la prima volta il tuo componente aggiuntivo e sono utili per insegnare ai nuovi utenti come interagire con il tuo componente aggiuntivo.
Definisci una home page per il tuo componente aggiuntivo specificandola nel manifest del progetto e implementando una o più funzioni homepageTrigger (vedi Configurazione della home page). Se il tuo
componente aggiuntivo estende Google Chat, la sua home page viene visualizzata nella
scheda Home di un messaggio diretto 1:1 con l'app
Chat ed è configurata nella console Google Cloud
anziché nel manifest (vedi
Configurare una home page per Chat).
Puoi avere più home page, una per ogni applicazione host estesa dal tuo componente aggiuntivo. Puoi anche definire una singola home page predefinita comune da utilizzare negli host in cui non hai specificato una home page personalizzata.
La home page del componente aggiuntivo viene visualizzata nei seguenti casi:
- Quando il componente aggiuntivo viene aperto per la prima volta nell'host (dopo l'autorizzazione) o quando un utente apre la scheda Home in un messaggio diretto 1:1 con la tua app di chat in Chat.
- Quando l'utente passa da un contesto contestuale a uno non contestuale mentre il componente aggiuntivo è aperto. Ad esempio, dalla modifica di un evento di Calendar al calendario principale.
- Quando l'utente fa clic sul pulsante Indietro un numero sufficiente di volte per far uscire una scheda su due dalle pile interne.
- Quando un'interazione con l'interfaccia utente in una scheda non contestuale genera una chiamata
Navigation.popToRoot.
È consigliabile progettare una home page. Se non ne definisci nessuna, viene utilizzata una scheda generica contenente il nome del componente aggiuntivo ogni volta che un utente naviga nella home page.
Configurazione della home page
I componenti aggiuntivi di Google Workspace utilizzano il campo addOns.common.homepageTrigger per
configurare i contenuti predefiniti (non contestuali)
del componente aggiuntivo per le applicazioni host nel
manifest del componente aggiuntivo:
{
"addOns": {
"common": {
"homepageTrigger": {
"runFunction": "myFunction",
"enabled": true
}
}
}
}
runFunction: il nome della funzione Google Apps Script che il framework dei componenti aggiuntivi di Google Workspace richiama per eseguire il rendering delle schede dei componenti aggiuntivi della home page. Questa funzione è la funzione di attivazione della home page. Questa funzione deve creare e restituire un array di oggettiCardche compongono l'interfaccia utente della home page. Se vengono restituite più schede, l'applicazione host mostra le intestazioni delle schede in un elenco che l'utente può selezionare (vedi Restituzione di più schede).enabled: indica se le schede della home page devono essere abilitate per questo ambito. Questo campo è facoltativo e il valore predefinito ètrue. Se imposti questo valore sufalse, le schede della home page vengono disattivate per tutti gli host (a meno che non venga eseguito l'override per l'host specifico; vedi la configurazione specifica dell'host).
Affinché un host possa utilizzare la home page comune, sia
addOns.common.homepageTrigger sia la risorsa di primo livello dell'host
devono essere presenti nel manifest del componente aggiuntivo. Ad esempio, se
addOns.gmail non è
presente nel manifest, il componente aggiuntivo viene disattivato
per Gmail e non mostra una home page o altre funzionalità
in questo host.
Oltre alla configurazione comune, gli override per host con struttura identica sono disponibili nella configurazione di ogni applicazione host, in addOns.gmail.homepageTrigger, addOns.calendar.homepageTrigger e altri trigger specifici dell'host.
L'esempio seguente mostra un manifest in cui è definito un trigger della home page comune, ma viene sostituito da funzioni personalizzate per Calendar e Drive e disabilitato per Gmail. In questa
configurazione, la funzione buildHomePage comune non viene mai eseguita perché è
sovrascritta o l'host è disattivato.
{
...
"addOns": {
...
"common": {
"homepageTrigger": { "runFunction": "buildHomePage" }
},
"calendar": {
"homepageTrigger": { "runFunction": "buildCalendarHomepage" }
},
"drive": {
"homepageTrigger": { "runFunction": "buildDriveHomepage" }
},
"gmail": {
"homepageTrigger": { "enabled": false }
},
...
}
}
Il seguente estratto del manifest è equivalente all'esempio precedente, anche
se la configurazione homepageTrigger predefinita e quella di Gmail
sono omesse:
{
"addOns": {
"common": {},
"calendar": {
"homepageTrigger": { "runFunction": "myCalendarFunction" }
},
"drive": {
"homepageTrigger": { "runFunction": "myDriveFunction" }
},
"gmail": {},
...
}
}
Nessuna delle sezioni homepageTrigger è obbligatoria. L'interfaccia utente mostrata per un
componente aggiuntivo in un prodotto host dipende dalla presenza
del campo manifest corrispondente e dall'eventuale presenza di un
homepageTrigger associato. L'esempio seguente mostra quali
funzioni di attivazione dei componenti aggiuntivi vengono eseguite per creare un'interfaccia utente
della home page per diverse configurazioni del file manifest:
Configurare una home page per Chat
A differenza di altre applicazioni host di Google Workspace, i componenti aggiuntivi che
estendono Chat non mostrano una home page nel riquadro di accesso
rapido a destra e non utilizzano addOns.common.homepageTrigger nel manifest.
Chat mostra invece la tua home page come scheda nella scheda Home
di un messaggio diretto 1:1 con l'app Chat.
Per attivare e configurare un trigger della home page dell'app per il tuo componente aggiuntivo di Chat nella console Google Cloud:
Nella console Google Cloud, vai a Menu > API e servizi > API e servizi abilitati > API Google Chat > Configurazione.
Nella sezione Funzionalità interattive, assicurati che l'opzione Attiva funzionalità interattive sia attivata, quindi seleziona la casella di controllo Supporta la home page dell'app.
In Impostazioni di connessione > Trigger, specifica il gestore della home page dell'app nel campo Home page dell'app in base all'architettura del componente aggiuntivo:
- HTTP: inserisci l'URL dell'endpoint HTTPS che gestisce le richieste della home page dell'app (o lascialo vuoto in modo che l'URL dell'endpoint HTTP comune riceva tutti gli eventi).
- Google Apps Script: inserisci il nome della funzione di callback di Google Apps Script
che crea e restituisce la scheda della home page (il valore predefinito è
onAppHome).
Fai clic su Salva.
Quando un utente apre la scheda Home di un messaggio diretto con la tua app di Chat, Chat invia un evento trigger Home app al tuo endpoint o alla tua funzione. Per eseguire il rendering della home page, restituisci un oggetto
RenderActions
con un'azione di navigazione pushCard (o utilizza updateCard quando aggiorni
la home page in risposta al clic di un pulsante nella scheda della home page):
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(); }
Per maggiori dettagli sulla gestione dei trigger di Chat e sulle azioni di ritorno, vedi Ricevere e rispondere alle interazioni degli utenti.
Oggetti evento della home page
Quando viene chiamata, alla funzione di attivazione della home page (runFunction) o all'endpoint della home page dell'app
descritto in precedenza viene passato un
oggetto evento contenente i dati del
contesto di chiamata.
Gli oggetti evento della home page non includono widget o informazioni contestuali. Le informazioni trasmesse includono i seguenti campi dell'oggetto evento comune:
commonEventObject.clientPlatformcommonEventObject.hostAppcommonEventObject.userLocaleecommonEventObject.userTimezone(vedi Accesso alle impostazioni internazionali e al fuso orario dell'utente per informazioni sulle limitazioni).
In Chat, l'oggetto evento della home page dell'app include anche il campo chat
con informazioni sull'utente e sull'ora di interazione:
chat.user: l'utente di Chat che ha aperto la scheda Home.chat.eventTime: il timestamp relativo al momento in cui l'utente ha aperto la scheda Home.
Per maggiori dettagli, consulta Oggetto evento.
Altre schede non contestuali
L'interfaccia utente del componente aggiuntivo può contenere schede aggiuntive non contestuali che non sono home page. Ad esempio, la home page potrebbe avere un pulsante che apre una scheda "Impostazioni" per regolare le impostazioni dei componenti aggiuntivi (queste impostazioni sono in genere indipendenti dal contesto).
Le schede non contestuali vengono create come qualsiasi altra scheda. L'unica differenza è l'azione o l'evento che genera e visualizza la scheda. Consulta Metodi di navigazione per informazioni dettagliate su come creare transizioni tra le schede.