Creare componenti aggiuntivi di Google Workspace

Questa pagina fornisce una panoramica su come progettare, creare e pubblicare componenti aggiuntivi di Google Workspace. Questa panoramica spiega i seguenti passaggi:

Determina le applicazioni di Google Workspace in cui vuoi che il componente aggiuntivo sia disponibile per gli utenti.
Configura i progetti del componente aggiuntivo e scegli un proprietario e dei collaboratori.
Progetta e configura l'aspetto e il comportamento del componente aggiuntivo.
Crea il componente aggiuntivo.
Verifica gli ambiti OAuth del componente aggiuntivo.
Testa il componente aggiuntivo in una o più applicazioni di Google Workspace.
Pubblica il componente aggiuntivo.

Puoi creare un componente aggiuntivo con Apps Script o HTTP. Per un confronto, guarda il video "Apps Script vs. HTTP endpoints: Which should you choose? 🤔".

Scegli le applicazioni host di Google Workspace

Puoi configurare i componenti aggiuntivi di Google Workspace in modo che vengano visualizzati nelle seguenti applicazioni host di Google Workspace:

Gmail
Google Calendar
Google Chat
Documenti Google
Google Drive
Google Meet
Fogli Google
Presentazioni Google

Per scoprire come creare componenti aggiuntivi per le applicazioni di Google Workspace, vedi Estendere l'interfaccia utente di Google Workspace.

Configura i progetti del componente aggiuntivo e scegli un proprietario e dei collaboratori

Se crei il componente aggiuntivo in Apps Script, devi creare sia un progetto Apps Script sia un progetto Google Cloud. Se crei il componente aggiuntivo in un linguaggio diverso da Apps Script, devi creare solo un progetto cloud di Google.

Prima di iniziare lo sviluppo del componente aggiuntivo, scegli un singolo account utente come proprietario dei progetti e decidi quali altri account saranno collaboratori. Il proprietario dei progetti crea e gestisce i file di progetto e le impostazioni associate, mentre i collaboratori possono aiutarti con la codifica e i test.

Progetti Apps Script

Prima di creare il componente aggiuntivo, consulta le quote e le limitazioni di Apps Script per assicurarti che la progettazione del progetto sia conforme a queste linee guida. Apps Script è ideale per lo sviluppo leggero di componenti aggiuntivi personali o interni con una piccola base di utenti. Se prevedi di creare un componente aggiuntivo su larga scala che deve gestire molti utenti, richiede una bassa latenza o un controllo completo dell'infrastruttura, valuta la possibilità di svilupparlo in un ambiente di runtime diverso.

Puoi creare i file di progetto Apps Script del componente aggiuntivo in un Drive condiviso in modo che nessun singolo account abbia la proprietà esclusiva. Se inserisci il file di script del componente aggiuntivo in un Drive condiviso, più collaboratori avranno accesso al progetto di script.

Quando pubblichi un componente aggiuntivo, un singolo account utente funge da publisher. L'account di pubblicazione deve avere accesso in modifica al progetto di script, ma non deve essere il proprietario.

Per creare un progetto Apps Script, vedi Progetti di script.

Progetti Google Cloud

Ti consigliamo di aggiungere collaboratori al progetto Cloud del componente aggiuntivo. In questo modo, un membro del tuo team potrà sempre accedere alle impostazioni Cloud del componente aggiuntivo.

Per creare un progetto Google Cloud, vedi Creare un progetto Google Cloud.

Progetta e configura l'aspetto e il comportamento del componente aggiuntivo

Prima di iniziare a creare il componente aggiuntivo, decidi come vuoi che appaia e come deve comportarsi. Valuta i casi d'uso per cui il componente aggiuntivo deve tentare di fornire soluzioni. Inizia con un design semplice per farlo funzionare, poi aggiungi ulteriori perfezionamenti.

Consulta la Guida di stile per i componenti aggiuntivi di Google Workspace per le linee guida su come progettare l'esperienza utente del componente aggiuntivo.

Configura il manifest del componente aggiuntivo

Dopo aver progettato il componente aggiuntivo, puoi iniziare a implementare il design nel manifest del componente aggiuntivo. Nel manifest configuri la maggior parte dell'aspetto e del comportamento del componente aggiuntivo, incluse le applicazioni host di Google Workspace che il componente aggiuntivo estende.

Per maggiori dettagli, vedi Manifest per i componenti aggiuntivi di Google Workspace.

Man mano che aggiungi codice e funzionalità al componente aggiuntivo, modifica il manifest in base alle esigenze per ottenere l'aspetto e il comportamento richiesti.

Configura l'aspetto e il comportamento dell'app Google Chat

Se hai progettato un componente aggiuntivo che estende Google Chat, devi utilizzare l'API Google Chat per configurare l'aspetto e il comportamento di un'app Chat. Per i passaggi, vedi Configurare un'app Google Chat.

Crea il componente aggiuntivo

Devi implementare un'interfaccia basata su schede per il componente aggiuntivo. Utilizza il servizio Card di Apps Script o, se scrivi in un altro linguaggio di codice, restituisci JSON formattato correttamente per il rendering dell'interfaccia come schede.

Devi anche implementare tutte le funzioni di attivazione specificate nel manifest del componente aggiuntivo. Se il tuo componente aggiuntivo si connette a un servizio di terze parti non Google utilizzando OAuth, devi configurare anche OAuth per quel servizio.

Crea le schede

Definisci un'interfaccia utente del componente aggiuntivo creando Card oggetti e riempiendoli con i widget. Le funzioni di attivazione specificate nel manifest devono restituire un singolo Card oggetto o un array di Card oggetti che rappresentano diverse 'pagine' dell'interfaccia del componente aggiuntivo. Il componente aggiuntivo può anche creare e visualizzare nuove schede in risposta alle azioni dell'utente.

In Apps Script, crei le schede utilizzando la CardBuilder classe. Ogni scheda richiede un CardHeader e una o più CardSections. Devi popolare ogni sezione della scheda con i singoli widget che compongono l'interfaccia del componente aggiuntivo. I widget di interazione sono in genere collegati alle azioni per definire il loro comportamento di interazione.

Dopo aver aggiunto tutte le sezioni e i widget alla scheda tramite il relativo CardBuilder, devi chiamare CardBuilder.build() per creare l'oggetto Card corrispondente.

Puoi utilizzare altri servizi integrati di Apps Script come CalendarApp per recuperare le informazioni da visualizzare nelle schede dei componenti aggiuntivi che crei. Puoi utilizzare i dati recuperati da servizi non Google.

Se il componente aggiuntivo deve accedere ad API non Google che richiedono OAuth, devi configurare e connetterti a quel servizio. Per maggiori dettagli, consulta la guida Connettersi a servizi non Google .

Ordine di creazione

Quando crei una scheda, devi farlo dall'alto verso il basso. Ovvero, devi utilizzare questo ordine di creazione:

Crea il widget.
Aggiungi il widget alla sezione della scheda.
Ripeti l'operazione finché la sezione della scheda non contiene tutti i widget.
Aggiungi la sezione della scheda alla scheda.

Questo è necessario perché quando aggiungi un widget a una scheda o a una sezione della scheda, in realtà stai aggiungendo una copia di quel widget. Le modifiche apportate all'oggetto widget dopo l'aggiunta non vengono riflesse nella scheda finale.

Azioni universali

Puoi utilizzare le azioni universali per fornire funzionalità indipendenti dal contesto. Le azioni universali sono voci di menu disponibili nell'interfaccia utente del componente aggiuntivo, indipendentemente dalla scheda visualizzata. Tutte le azioni universali definite vengono sempre visualizzate nel menu della scheda del componente aggiuntivo.

Per maggiori dettagli , vedi Azioni universali.

Verifica gli ambiti OAuth del componente aggiuntivo

Gli ambiti definiscono le azioni che il componente aggiuntivo è autorizzato a intraprendere per conto di un utente. È una best practice che i componenti aggiuntivi abbiano solo gli ambiti per le azioni che devono avere per funzionare e nient'altro.

Nei progetti di componenti aggiuntivi, imposta esplicitamente gli ambiti del componente aggiuntivo per assicurarti che utilizzi il set di ambiti meno permissivo possibile. Definisci gli ambiti utilizzati dal componente aggiuntivo in the add-on manifest.

Per maggiori dettagli, vedi Ambiti.

Testa il componente aggiuntivo

Puoi testare i componenti aggiuntivi non pubblicati installandoli prima. Una volta installato e autorizzato, puoi utilizzare il componente aggiuntivo nel tuo account e testarne l'aspetto e il comportamento nelle applicazioni host che estende. Devi verificare che il componente aggiuntivo si comporti come previsto per i contesti e le azioni dell'utente.

Per iniziare a testare il componente aggiuntivo, consulta le seguenti guide:

Pubblica il componente aggiuntivo

La pubblicazione del componente aggiuntivo lo rende disponibile ad altri utenti, pubblicamente o solo agli utenti del tuo dominio. Prima di iniziare la procedura di pubblicazione, assicurati di consultare la panoramica della pubblicazione. La pubblicazione è una procedura complessa che richiede preparazione e tempo per essere completata.

I componenti aggiuntivi di Google Workspace vengono pubblicati su Google Workspace Marketplace. I componenti aggiuntivi disponibili pubblicamente devono completare la revisione dell'app prima di essere pubblicati.

Per maggiori dettagli, vedi Pubblicare un componente aggiuntivo di Google Workspace per maggiori dettagli.