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:

1. Determina le applicazioni Google Workspace in cui vuoi che il tuo componente aggiuntivo sia disponibile per gli utenti.
2. Configura i progetti del componente aggiuntivo e scegli un proprietario e i collaboratori.
3. Progetta e configura l'aspetto e il comportamento del componente aggiuntivo.
4. Crea il componente aggiuntivo.
5. Verifica gli ambiti OAuth del componente aggiuntivo.
6. Testa il componente aggiuntivo in una o più applicazioni Google Workspace.
7. 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? 🤔".

Scegliere 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 per le applicazioni Google Workspace, consulta la sezione Estendere la UI di Google Workspace.

Configurare i progetti del componente aggiuntivo e scegliere un proprietario e dei collaboratori

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

Prima di iniziare lo sviluppo di componenti aggiuntivi, scegli un singolo account utente che possieda i progetti e decidi quali altri account sono collaboratori. Il proprietario dei progetti crea e gestisce i file di progetto e le impostazioni associate, mentre i collaboratori possono aiutare con la codifica e i test.

Avviso: se non aggiungi collaboratori ai tuoi progetti di componenti aggiuntivi, è fondamentale che tu ne trasferisca la proprietà prima che l'account del proprietario venga chiuso o rimosso. In caso contrario, potresti perdere completamente l'accesso al codice e alle impostazioni del componente aggiuntivo.

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 in linea con queste linee guida. Apps Script è ideale per lo sviluppo leggero di componenti aggiuntivi personali o interni con una piccola base utenti. Se prevedi di creare un componente aggiuntivo su larga scala che deve gestire molti utenti, richiede una bassa latenza o esige il controllo completo della tua infrastruttura, valuta di svilupparlo in un ambiente di runtime diverso.

Puoi creare i file di progetto Apps Script del tuo componente aggiuntivo in un Drive condiviso in modo che nessun singolo account ne 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 disporre dell'accesso in modifica al progetto dello script, ma non deve esserne 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 può sempre accedere alle impostazioni cloud del componente aggiuntivo.

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

Progettare e configurare l'aspetto e il comportamento del componente aggiuntivo

Decidi l'aspetto e il comportamento del componente aggiuntivo prima di iniziare a crearlo. Considera per quali casi d'uso il componente aggiuntivo dovrebbe tentare di fornire soluzioni. Inizia con un design semplice per iniziare a lavorare, poi aggiungi altri perfezionamenti.

Suggerimento:inizia con una semplice scheda della home page, poi aggiungi altri widget, schede, navigazione e altri comportamenti. Puoi anche prendere in considerazione le schede contestuali attivate dall'azione di un utente nell'applicazione host, ad esempio l'apertura di una conversazione di Gmail o di un evento di Calendar.

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

Configurare il manifest del componente aggiuntivo

Dopo aver progettato il componente aggiuntivo, puoi iniziare a implementare il design nel manifest del componente aggiuntivo. Il manifest è il file in cui 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 informazioni dettagliate, vedi Manifest per il componente aggiuntivo 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 del componente aggiuntivo.

Configurare 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 di chat. Per i passaggi, consulta 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 programmazione, restituisci JSON formattato correttamente per il rendering dell'interfaccia come schede.

Devi anche implementare 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 anche configurare OAuth per quel servizio.

Costruire carte

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

In Apps Script, le schede vengono create utilizzando la classe CardBuilder. Ogni scheda richiede un CardHeader e uno o più CardSections. Devi compilare 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 tutti i widget alla scheda tramite il relativo CardBuilder, devi chiamare CardBuilder.build() per creare l'oggetto Card corrispondente.

Nota: se non chiami build() dopo aver utilizzato le classi builder nel servizio schede, si verificano errori di tipo. Le funzioni di attivazione, ad esempio, devono restituire oggetti Card. La restituzione di oggetti CardBuilder comporta invece un errore.

Puoi utilizzare altri servizi Apps Script integrati 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 tuo componente aggiuntivo deve accedere ad API non Google che richiedono OAuth, devi configurare e connetterti a quel servizio. Per maggiori dettagli, consulta la guida alla connessione a servizi non Google.

Ordine di costruzione

Quando crei una scheda, devi procedere dall'alto verso il basso. ovvero devi utilizzare questo ordine di costruzione:

1. Crea il widget.
2. Aggiungi il widget alla sezione delle schede.
3. Ripeti l'operazione finché la sezione della scheda non contiene tutti i widget.
4. Aggiungi la sezione della carta alla carta.

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

Avviso: aggiungi un widget a una scheda o a una sezione di schede solo dopo averlo creato. Aggiungi una sezione a una scheda solo dopo che è stata completamente compilata con i relativi widget. Non modificare i widget o le sezioni dopo averli aggiunti. Se vuoi apportare una modifica a un widget aggiunto, devi ricreare la sezione o la scheda a cui è stato aggiunto.

Universal Action

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, consulta 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 per i componenti aggiuntivi avere solo gli ambiti per le azioni che devono svolgere per funzionare e nient'altro.

Nei progetti dei componenti aggiuntivi, imposta in modo esplicito gli ambiti del componente aggiuntivo per assicurarti che il componente aggiuntivo utilizzi il set di ambiti meno permissivo possibile. Definisci gli ambiti utilizzati dal componente aggiuntivo nel manifest del componente aggiuntivo.

Per maggiori dettagli, consulta la sezione Ambiti.

Testa il componente aggiuntivo

Puoi testare i componenti aggiuntivi non pubblicati installandoli per primi. 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 degli utenti.

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

• Testare ed eseguire il debug dei componenti aggiuntivi di Google Workspace di Apps Script
• Testare ed eseguire il debug dei componenti aggiuntivi HTTP di Google Workspace
• Testare le funzionalità interattive per le app Google Chat

Pubblicare 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 rivedere 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, consulta Pubblicazione di componenti aggiuntivi di Google Workspace.