Creare componenti aggiuntivi per Google Workspace

Se vuoi creare un nuovo componente aggiuntivo di Google Workspace, segui questa procedura generale:

1. Configura i progetti del tuo componente aggiuntivo e scegli un proprietario e i collaboratori.
2. Progetta l'aspetto e il comportamento del tuo componente aggiuntivo.
3. Configura il manifest del progetto o la risorsa di deployment del componente aggiuntivo.
4. Scrivi il codice per definire l'aspetto e il comportamento del componente aggiuntivo.
5. Verifica gli ambiti OAuth del componente aggiuntivo.
6. Testa il componente aggiuntivo nelle applicazioni host che estende.
7. Pubblica il componente aggiuntivo.

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

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

Prima di iniziare lo sviluppo di componenti aggiuntivi, scegli un singolo account utente per proprietà dei progetti e decidere quali altri account sono collaboratori. Il proprietario dei progetti crea e gestisce i file dei progetti e le impostazioni associate, mentre i collaboratori possono aiutarti con la programmazione e i test.

Avviso :se non aggiungi collaboratori ai progetti aggiuntivi, è fondamentale trasferirne 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 di progetto per Apps Script del tuo componente aggiuntivo in un Drive condiviso in modo che nessun account sia proprietario esclusivo. Inserire il file degli script dei componenti aggiuntivi in un Drive condiviso ti consente di assicurarti che più collaboratori abbiano sempre 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.

Progetti Google Cloud

Ti consigliamo di aggiungere collaboratori al progetto cloud del componente aggiuntivo. In questo modo puoi garantire che tutti i membri del tuo team possano sempre accedere alle impostazioni cloud del componente aggiuntivo.

Progettazione dell'aspetto e del comportamento dei componenti aggiuntivi

Decidi come deve essere il componente aggiuntivo e come deve comportarsi prima di iniziare a crearlo. Pensa ai casi d'uso in cui il componente aggiuntivo deve tentare di fornire soluzioni. Inizia con un design semplice per iniziare, quindi aggiungi ulteriori perfezionamenti.

Suggerimento: inizia con una semplice scheda della home page, quindi aggiungi altri widget, schede, navigazione e altri comportamenti. Puoi anche prendere in considerazione le schede contestuali attivate da un'azione dell'utente nell'applicazione host, come l'apertura di un thread di messaggi Gmail o di un evento Calendar.

Per informazioni su come progettare l'esperienza utente dei componenti aggiuntivi, consulta la guida di stile dei componenti aggiuntivi di Google Workspace.

Configura il manifest del progetto del componente aggiuntivo

Nei progetti Apps Script, il manifest del progetto è un file JSON speciale. Specifica una varietà di dettagli sul progetto, ad esempio le dipendenze delle librerie. Per i componenti aggiuntivi di Google Workspace, il manifest fornisce anche le informazioni di base necessarie all'applicazione host per mostrare correttamente il componente aggiuntivo.

Per informazioni dettagliate su come configurare il manifest del componente aggiuntivo in Apps Script, consulta la sezione Manifest.

Man mano che aggiungi codice e funzionalità al tuo componente aggiuntivo, modifica il manifest in base alle tue esigenze per produrre l'aspetto e il comportamento del componente aggiuntivo richiesto.

Codifica del componente aggiuntivo

Devi implementare un'interfaccia basata su schede per il componente aggiuntivo. Utilizza Servizio schede di Apps Script oppure, se stai scrivendo in un altro linguaggio di codice, restituisci il formato JSON formattato correttamente per la visualizzazione dell'interfaccia come schede.

Devi inoltre implementare le eventuali funzioni trigger specificate nel manifest del componente aggiuntivo. Se il componente aggiuntivo si connette a un servizio di terze parti e non Google utilizzando OAuth, devi configurare anche OAuth per tale servizio.

Creazione carte

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

In Apps Script, puoi creare le schede utilizzando la classe CardBuilder. Ogni scheda richiede una CardHeader e una o più CardSections. Ogni sezione della scheda deve essere compilata con i singoli widget che compongono l'interfaccia del componente aggiuntivo. I widget di interazione, in genere sono collegati ad azioni per definirne il comportamento.

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

Nota: se non riesci a chiamare build() dopo aver utilizzato le classi di builder nel servizio Card, vengono generati errori di tipo. Le funzioni trigger, ad esempio, devono restituire oggetti Card. La restituzione di oggetti CardBuilder restituisce invece un errore.

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

Per i componenti aggiuntivi di Google Workspace che richiedono l'accesso alle API non Google che richiedono OAuth, devi configurare e connetterti a quel servizio. Per ulteriori dettagli, consulta la guida al collegamento a servizi non Google.

Ordine di costruzione

Quando crei una carta, devi costruire dall'alto. Vale a dire che devi utilizzare questo ordine di costruzione:

1. Crea il widget.
2. Aggiungi il widget alla sezione della scheda.
3. Ripeti la procedura fino alla sezione della scheda con tutti i relativi widget.
4. Aggiungi la sezione della carta.

Questa operazione è necessaria perché, quando aggiungi un widget a una scheda o a una sezione della scheda, stai aggiungendo una copia di quel widget. Le eventuali modifiche apportate all'oggetto widget dopo l'aggiunta non verranno riportate nella scheda finale.

Avviso: aggiungi un widget a una scheda o a una sezione della scheda solo dopo aver completato la creazione. Aggiungi una sezione della scheda a una scheda solo dopo che è stata completata completamente 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.

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 attualmente visualizzata. Tutte le azioni universali definite vengono sempre visualizzate nel menu della scheda del componente aggiuntivo.

Per ulteriori dettagli, consulta Azioni universali.

Verifica 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 prevede che i componenti aggiuntivi dispongano di ambiti per le azioni che devono avere in funzione e nient'altro.

Nei progetti di componenti aggiuntivi, imposta esplicitamente gli ambiti dei componenti aggiuntivi per assicurarti che utilizzino il set di ambiti meno permissivo possibile. Sei tu a definire gli ambiti che verranno utilizzati dal componente aggiuntivo del componente aggiuntivo.

Per ulteriori dettagli, consulta la sezione Ambiti.

Testare il componente aggiuntivo

Puoi testare i componenti aggiuntivi non pubblicati installando prima 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 che estende. Dovresti verificare che il componente aggiuntivo si comporti come previsto per i contesti e le azioni degli utenti.

Per ulteriori dettagli, consulta Testare componenti aggiuntivi di Google Workspace.

Pubblicare il componente aggiuntivo

La pubblicazione del componente aggiuntivo lo rende disponibile ad altri utenti, pubblicamente o solo nel tuo dominio. Prima di iniziare la procedura di pubblicazione, consulta la panoramica sulla pubblicazione. La pubblicazione è un processo complesso che richiede preparazione e tempo di completamento.

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 del componente aggiuntivo di Google Workspace.

Esempio di componente aggiuntivo di Google Workspace

Per aiutarti a capire come sono creati i componenti aggiuntivi di Google Workspace, la guida rapida ai componenti aggiuntivi di Google Workspace ti mostra come creare un semplice componente aggiuntivo di Google Workspace, incluse le home page, la navigazione nelle schede e le connessioni a un servizio di terze parti. Una volta completata la guida rapida, puoi installare il componente aggiuntivo e sperimentare con il codice.