Creare componenti aggiuntivi di Google Workspace

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

1. Determina le applicazioni Google Workspace in cui vuoi che il tuo plug-in sia disponibile per gli utenti.
2. Configura i progetti del tuo componente aggiuntivo e scegli un proprietario e i collaboratori.
3. Progetta e configura l'aspetto e il comportamento del componente aggiuntivo.
4. Compila 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.

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 (anteprima per gli sviluppatori)
• Documenti Google
• Google Drive
• Fogli Google
• Presentazioni Google

Per scoprire come eseguire il build per le applicazioni Google Workspace, consulta Estendere l'interfaccia utente di Google Workspace.

Configura i progetti del tuo componente aggiuntivo e scegli 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 tuo componente aggiuntivo in un linguaggio diverso da Apps Script, devi solo creare un progetto Google Cloud.

Prima di iniziare a sviluppare il componente aggiuntivo, scegli un singolo account utente che possiede i progetti e decidi quali altri account sono collaboratori. Il proprietario dei progetti crea e gestisce i file del progetto e le impostazioni associate, mentre i collaboratori possono fornire assistenza per la programmazione e i test.

Avviso: se non aggiungi collaboratori ai progetti dei 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

Puoi creare i file del 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 script del componente aggiuntivo in un Drive condiviso, più collaboratori avranno accesso al progetto dello script.

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

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

Progetti Google Cloud

Ti consigliamo di aggiungere collaboratori al progetto Cloud del plug-in. In questo modo, un membro del tuo team può sempre accedere alle impostazioni di 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

Prima di iniziare a creare il componente aggiuntivo, decidi come deve apparire e come deve comportarsi. Valuta per quali casi d'uso il plug-in deve tentare di fornire soluzioni. Inizia con un design semplice per iniziare a lavorare, quindi aggiungi ulteriori perfezionamenti.

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

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.

Configurare il manifest del componente aggiuntivo

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

Per informazioni dettagliate, vedi Manifest per il componente aggiuntivo 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.

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

Anteprima per sviluppatori: disponibile nell'ambito del Programma Anteprima per sviluppatori di Google Workspace, che concede l'accesso in anteprima a determinate funzionalità.

Se hai progettato un componente aggiuntivo che espande Google Chat, devi utilizzare l'API Google Chat per configurare l'aspetto e il comportamento di un'app di Chat. Per la procedura, consulta Configurare un'app Google Chat.

Crea il componente aggiuntivo

Devi implementare un'interfaccia basata su schede per il plug-in. Utilizza il servizio Schede di Apps Script o, se scrivi in un altro linguaggio di codice, restituisci JSON formattato correttamente per consentire all'interfaccia di eseguire il rendering come schede.

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

Carte di costruzione

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

In Apps Script, crei le schede 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 solitamente 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.

Nota: la mancata chiamata a build() dopo l'utilizzo delle classi di builder nel servizio Schede genera errori di tipo. Ad esempio, le funzioni di attivazione devono restituire oggetti Card. Se restituisci oggetti CardBuilder, viene generato un errore.

Puoi utilizzare altri servizi di 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 ha bisogno di accedere ad API non Google che richiedono OAuth, devi configurare e connetterti a quel servizio. Per ulteriori dettagli, consulta la guida alla connessione ai servizi non Google.

Ordine di costruzione

Quando crei una scheda, devi iniziare dall'alto verso il basso. In altre parole, devi utilizzare questo ordine di compilazione:

1. Crea il widget.
2. Aggiungi il widget alla sezione della scheda.
3. Ripeti finché la sezione della scheda non contiene tutti i widget.
4. 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à aggiungi una copia del widget. Eventuali modifiche apportate all'oggetto widget dopo averlo aggiunto non vengono riportate nella scheda finale.

Avviso: aggiungi un widget a una scheda o a una sezione della scheda solo dopo aver completato la sua creazione. Aggiungi una sezione a una scheda solo dopo averla completata con i 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.

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, consulta Azioni universali.

Verificare gli ambiti OAuth del componente aggiuntivo

Gli ambiti definiscono le azioni che il componente aggiuntivo può eseguire per conto di un utente. È una best practice per i componenti aggiuntivi avere ambiti solo per le azioni che devono avere per funzionare e nient'altro.

Nei progetti dei componenti aggiuntivi, imposta in modo esplicito gli scopi del componente aggiuntivo per assicurarti che utilizzi l'insieme di scopi meno permissivi possibile. Puoi definire gli ambiti utilizzati dal componente aggiuntivo nel manifest del componente aggiuntivo.

Per ulteriori dettagli, consulta la sezione Ampi dello spettro.

Testare il componente aggiuntivo

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

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

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

Pubblicare il componente aggiuntivo

Se pubblichi il tuo componente aggiuntivo, lo rendi disponibile per altri utenti, in modo pubblico o solo per gli utenti del tuo dominio. Prima di iniziare la procedura di pubblicazione, consulta la panoramica della pubblicazione. La pubblicazione è un processo complesso 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 la sezione Pubblicazione del componente aggiuntivo di Google Workspace.