Best practice

Migliora l'esperienza complessiva dei tuoi utenti seguendo queste guide per il design dei componenti aggiuntivi.

Best practice generali

Ti invitiamo a seguire le best practice riportate di seguito per tutti gli 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 proprietario del progetto e quale account funge da editore. Determina anche quali account devono fungere da collaboratori e assicurati che questi account abbiano accesso al progetto dello script e al relativo progetto della piattaforma Cloud associato.

Nota: è importante pianificare la proprietà dei componenti aggiuntivi. Se il proprietario del componente aggiuntivo lascia la tua organizzazione, devi assicurarti che la proprietà venga trasferita, altrimenti potresti perdere la possibilità di aggiornare e gestire il componente aggiuntivo. Per questo motivo, potrebbe essere meglio creare un account dell'organizzazione specificamente per possedere e pubblicare i componenti aggiuntivi dell'organizzazione. Puoi anche utilizzare un Drive condiviso per agire come proprietario del progetto di script, ma un account specifico deve agire come publisher del componente aggiuntivo.

Estendi Google Workspace, non replicarlo

I componenti aggiuntivi hanno lo scopo di fornire nuove funzionalità alle applicazioni Google Workspace che estendono o di automatizzare attività complesse. I componenti aggiuntivi che semplicemente replicano le funzionalità già presenti nell'applicazione o che non apportano miglioramenti significativi a un flusso di lavoro non hanno molte probabilità di superare la revisione dei componenti aggiuntivi per la pubblicazione.

Mantieni gli ambiti ristretti

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

Evita di fare troppo affidamento sulle librerie

L'utilizzo delle librerie di Apps Script può causare un funzionamento più lento del componente aggiuntivo rispetto a quanto accaderebbe se tutto il codice di Apps Script fosse contenuto in un singolo progetto di script. Sebbene le librerie di Apps Script funzionino nei componenti aggiuntivi, potresti riscontrare riduzioni del rendimento se le utilizzi. Evita di includere librerie non necessarie nel progetto e valuta i modi per ridurre la dipendenza del tuo componente aggiuntivo da queste librerie.

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

Utilizzare solo alcune schede

Se il componente aggiuntivo utilizza troppe schede, la configurazione della 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 Card o altri oggetti dell'interfaccia utente complessi, ti consigliamo di inserirlo in una funzione a parte. Questa funzione di creazione deve semplicemente creare l'oggetto e restituirlo. In questo modo, puoi rigenerare rapidamente l'oggetto ogni volta che è necessario aggiornare l'interfaccia utente. Ricorda di chiamare build() dopo aver utilizzato le classi di builder nel servizio Schede.

Mantieni le schede semplici

Se una 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 dell'interfaccia utente comprimibili, questo nasconde le informazioni all'utente. Cerca di semplificare il tuo 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, dovrebbe essere visualizzata una scheda con le informazioni sull'errore e le istruzioni su come correggerlo, se possibile. Ad esempio, se il tuo componente aggiuntivo non è riuscito a connettersi a un servizio non Google perché l'autorizzazione non è andata a buon fine, mostra una scheda che lo indica 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. 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 per le azioni, solitamente devi creare un oggetto di risposta. Puoi utilizzare istruzioni come quelle riportate di seguito per verificare che le risposte vengano costruite correttamente:

    Logger.log(response.printJson());

Esegui le funzioni di test che crei direttamente dall'editor di Apps Script utilizzando il menu Esegui. Quando hai un componente aggiuntivo funzionante, assicurati di installare la versione non pubblicata per poterlo testare.

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

Best practice per le conferenze di Calendar

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

Conservare la luce onCreateFunction

Ogni 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 eseguano solo il minimo necessario per creare la conferenza. Se fai troppo in queste funzioni, l'esperienza utente del tuo componente aggiuntivo potrebbe risultare lenta.

Utilizza i campi ConferenceData appropriati per i dati della conferenza

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

Non aggiungere i dettagli della conferenza all'evento di Google Calendar

Il componente aggiuntivo non deve aggiungere informazioni sulle conferenze di terze parti create alla descrizione dell'evento di Google Calendar. Google Calendar lo fa automaticamente, se necessario.