Creare componenti aggiuntivi per Google Workspace

Se vuoi creare un nuovo Google Workspace componente aggiuntivo, 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.

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.

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

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 Google Workspace i componenti aggiuntivi, 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.

Nello script App, 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.

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.

Se il Google Workspace componente aggiuntivo richiede l'accesso alle API non Google che richiedono OAuth, devi configurare e connetterti al 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.

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 Test Google Workspace Componenti aggiuntivi.

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.

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

Per maggiori dettagli, consulta Pubblicazione Google Workspace Componente aggiuntivo.

Google Workspace Esempio di componente aggiuntivo

 Barra lateraleGoogle Workspace

Per aiutarti a capire come sono creati Google Workspace i componenti aggiuntivi, la Google Workspace guida rapida ai componenti aggiuntivi di Gatto ti mostra come creare un semplice componente aggiuntivo, 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.