Best practice

Migliora l'esperienza complessiva dei tuoi utenti seguendo queste guide per la progettazione di componenti aggiuntivi.

Best practice generali

Ti consigliamo di seguire le seguenti best practice per tutti i componenti aggiuntivi sviluppati.

Determinare la proprietà del componente aggiuntivo prima di iniziare

I componenti aggiuntivi vengono definiti dai progetti Apps Script, che devono essere di proprietà di un account specifico o inseriti in un Drive condiviso. Prima di programmare un componente aggiuntivo, determina quale account deve essere proprietario del progetto e quale account agisce come editore. Stabilisci anche quali account devono avere la funzione di collaboratori e assicurati che questi account abbiano accesso al progetto di script e al progetto Cloud Platform associato.

Estendere Google Workspace, non replicarlo

I componenti aggiuntivi hanno lo scopo di fornire nuove funzionalità alle applicazioni Google Workspace che estendono o di automatizzare le attività complesse. È improbabile che i componenti aggiuntivi che si limitano a replicare la funzionalità già all'interno dell'applicazione o quelli che non migliorano notevolmente il flusso di lavoro per la revisione del componente aggiuntivo ai fini della pubblicazione.

Limitare gli ambiti

Quando definisci gli ambiti in modo esplicito, scegli sempre l'insieme di ambiti meno permissivo possibile. Ad esempio, se la tua richiesta di componente aggiuntivo non ha accesso completo al calendario dell'utente con l'ambito https://www.googleapis.com/auth/calendar, se ha bisogno solo dell'accesso in lettura, Per l'accesso in sola lettura, utilizza l'ambito https://www.googleapis.com/auth/calendar.readonly.

Evita di fare troppo affidamento sulle raccolte

L'uso delle librerie di Apps Script può causare un'esecuzione più lenta del componente aggiuntivo rispetto all'uso di tutto il codice di Apps Script all'interno di un singolo progetto di script. Anche se le librerie di Apps Script funzionano nei componenti aggiuntivi, è possibile che vengano applicate delle riduzioni delle prestazioni. Evita di includere librerie non necessarie nel tuo progetto e valuta i modi per ridurre la dipendenza del componente aggiuntivo.

La latenza descritta sopra si applica solo ai progetti Apps Script utilizzati come librerie lato server. Puoi utilizzare liberamente le librerie JavaScript lato client come jQuery, senza riscontrare questa latenza.

Best practice per i componenti aggiuntivi di Google Workspace

Le seguenti best practice si applicano solo ai componenti aggiuntivi di Google Workspace e all'utilizzo del servizio carte.

Usare solo poche schede

Se il componente aggiuntivo utilizza troppe schede, la configurazione di navigazione diventa complessa e difficile da gestire.

Evita l'impulso di creare più schede del necessario.

Usare le funzioni di creazione dei widget

Quando scrivi codice che crea Card o altri oggetti dell'interfaccia utente complessi, valuta di includere il codice nella relativa funzione. Questa funzione di creazione deve semplicemente creare l'oggetto e restituirlo. Questo consente di rigenerare rapidamente l'oggetto ogni volta che l'UI deve essere aggiornata. Ricorda di chiamare build() dopo aver utilizzato le classi di creazione nel servizio carte.

Semplicità delle schede

Se una determinata scheda ha troppi widget, può occupare troppo spazio sullo schermo e risultare meno utile. Mentre le sezioni delle schede di grandi dimensioni vengono visualizzate come elementi dell'interfaccia utente comprimibili, le informazioni vengono nascoste all'utente. Cerca di semplificare il componente aggiuntivo e di fornire esattamente ciò di cui l'utente ha bisogno e non più.

Utilizzare le schede di errore

Creare schede per le condizioni di errore. Se il componente aggiuntivo genera un errore, dovrebbe visualizzare una scheda con le informazioni sull'errore e le istruzioni su come correggerlo, se possibile. Ad esempio, se il componente aggiuntivo non è riuscito a connettersi a un servizio non Google perché l'autorizzazione non è andata a buon fine, mostra una scheda in cui viene indicato questo aspetto e chiedi all'utente di verificare i dati dell'account in uso.

Scrivere test e messaggi di test

Ti consigliamo di testare accuratamente tutti i componenti aggiuntivi che crei. Creare funzioni di test che creano schede e widget utilizzando i dati di test e verificare che gli oggetti siano creati come previsto.

Quando utilizzi le funzioni di callback di azione, solitamente devi creare un oggetto di risposta. Puoi utilizzare istruzioni come le seguenti per verificare che le risposte vengano create correttamente:

    Logger.log(response.printJson());

Esegui funzioni di test create direttamente dall'editor di Apps Script utilizzando il menu Esegui. Se un componente aggiuntivo è funzionante, assicurati di installare la versione non pubblicata in modo da poterlo testare.

Utilizza i dati di test appropriati per ogni applicazione host estesa dal componente aggiuntivo. Ad esempio, se il componente aggiuntivo estende Gmail, probabilmente hai bisogno di alcune email di test e dei relativi ID messaggio per assicurarti che il componente funzioni come previsto quando vengono forniti contenuti dei messaggi diversi. Puoi ottenere l'ID di un determinato messaggio elencando i messaggi tramite il metodo Users.messages.list dell'API Gmail oppure utilizzando il servizio Gmail di Apps Script.

Best practice per le conferenze di Calendar

Se il componente aggiuntivo integra le opzioni di conferenza di calendario di terze parti in Google Calendar, segui queste best practice aggiuntive:

Mantieni la luce onCreateFunction

Ogni elemento onCreateFunction che definisci nel manifest viene chiamato in modo sincrono quando un utente tenta di creare una soluzione per conferenze di quel tipo. Assicurati che queste funzioni svolgano solo il lavoro minimo necessario per creare la conferenza. Se esegui troppe operazioni in queste funzioni, il componente aggiuntivo potrebbe rallentare l'esperienza utente.

Utilizzare i campi ConferenceData appropriati per i dati relativi alle conferenze

Quando crei oggetti ConferenceData, puoi completarli con i dettagli relativi alla conferenza (codici di accesso, numeri di telefono, segnaposto, URI e così via). Assicurati di utilizzare il campo EntryPoint corrispondente per queste informazioni. Non inserire questi dettagli nel campo delle note ConferenceData.

Non aggiungere dettagli relativi alla conferenza all'evento di Google Calendar

Il componente aggiuntivo non deve necessariamente aggiungere informazioni sulla conferenza di terze parti creata alla descrizione dell'evento di Google Calendar. Google Calendar esegue questa operazione automaticamente quando necessario.