Best practice

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

Best practice generali

Ti consigliamo di utilizzare le seguenti best practice per tutti i componenti aggiuntivi che sviluppi.

Determinare la proprietà del componente aggiuntivo prima di iniziare

I componenti aggiuntivi sono definiti dai progetti Apps Script, che devono essere di proprietà di un account specifico o essere inseriti in un Drive condiviso. Prima di scrivere il codice di un componente aggiuntivo, determina quale account deve essere il proprietario del progetto e quale account funge da publisher. Determina anche quali account devono fungere da collaboratori e assicurati che questi account abbiano accesso al progetto di script e al progetto Google Cloud associato .

Estendere Google Workspace, non replicarlo

I componenti aggiuntivi sono progettati per fornire nuove funzionalità alle applicazioni Google Workspace che estendono o per automatizzare attività complesse. È improbabile che i componenti aggiuntivi che replicano semplicemente le funzionalità già presenti nell' applicazione o che non apportano miglioramenti significativi a un flusso di lavoro superino la revisione dei componenti aggiuntivi per la pubblicazione.

Mantenere gli ambiti ristretti

Quando definisci gli ambiti in modo esplicito, scegli sempre il set di ambiti meno permissivo possibile. Ad esempio, non fare in modo che il componente aggiuntivo richieda l'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.

Evitare di fare troppo affidamento sulle raccolte

L'utilizzo delle raccolte Apps Script può rallentare l'esecuzione del componente aggiuntivo rispetto a quando tutto il codice Apps Script è contenuto in un singolo progetto di script. Sebbene le raccolte Apps Script funzionino nei componenti aggiuntivi, potresti riscontrare una riduzione delle prestazioni se le utilizzi. Evita di includere raccolte non necessarie nel tuo progetto e valuta come ridurre la dipendenza del componente aggiuntivo da queste raccolte.

La latenza descritta sopra si applica solo ai progetti Apps Script utilizzati come raccolte lato server. Puoi utilizzare liberamente le raccolte 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 Card.

Utilizzare solo poche schede

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

Evita di creare più schede del necessario.

Utilizzare le funzioni di creazione dei widget

Quando scrivi codice che crea un Card o altri oggetti UI complessi, valuta la possibilità di inserire il codice in una funzione separata. Questa funzione di creazione deve solo creare l'oggetto e restituirlo. In questo modo puoi 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 Card.

Mantenere le schede semplici

Se una determinata scheda contiene troppi widget, può occupare troppo spazio sullo schermo e diventare meno utile. Sebbene le sezioni delle schede di grandi dimensioni vengano visualizzate come elementi UI 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 di più.

Utilizzare le schede di errore

Crea schede per le condizioni di errore. Se il componente aggiuntivo genera un errore, deve 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 è riuscita, visualizza una scheda che lo indica e chiedi all'utente di verificare le informazioni dell'account utilizzate.

Scrivere test e messaggi di test

Devi testare attentamente tutti i componenti aggiuntivi che crei. Crea funzioni di test che creano schede e widget utilizzando i dati di test, quindi verifica che gli oggetti vengano creati come previsto.

Quando utilizzi le funzioni di callback delle azioni, in genere 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 le funzioni di test che crei direttamente dall'editor Apps Script utilizzando il menu Esegui. Quando hai un componente aggiuntivo funzionante, assicurati di installare la versione non pubblicata in modo da poterla testare.

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

Best practice per le videoconferenze di Calendar

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

Ogni onCreateFunction definita nel manifest viene chiamata in modo sincrono quando un utente tenta di creare una soluzione per videoconferenze di quel tipo. Assicurati che queste funzioni eseguano solo il lavoro minimo necessario per creare la videoconferenza. Se queste funzioni eseguono troppe operazioni, l'esperienza utente del componente aggiuntivo potrebbe essere lenta.

Utilizzare i campi ConferenceData appropriati per i dati della videoconferenza

Quando crei ConferenceData oggetti, puoi popolarli con i dettagli della videoconferenza (codici di accesso, numeri di telefono, PIN, 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 i dettagli della videoconferenza all'evento di Calendar

Il componente aggiuntivo non deve aggiungere informazioni sulle videoconferenze di terze parti create alla descrizione dell'evento di Calendar. Calendar lo fa automaticamente quando necessario.