Melhore a experiência geral dos usuários seguindo estes guias de design de complementos.
Práticas recomendadas gerais
Recomendamos que você use as práticas recomendadas a seguir em todos os complementos que desenvolver.
Determine a propriedade do complemento antes de começar
Os complementos são definidos por projetos do Apps Script, que precisam ser de propriedade de uma conta específica ou colocados em um drive compartilhado. Antes de programar um complemento, determine qual conta deve ser proprietária do projeto e qual conta atua como publisher. Determine também quais contas vão atuar como colaboradores e verifique se elas têm acesso ao projeto de script e ao projeto do Google Cloud associado.
Amplie o Google Workspace, não o replique
Os complementos oferecem novos recursos aos aplicativos do Google Workspace que eles estendem ou automatizam tarefas complexas. Os complementos que apenas replicam funcionalidades já presentes no aplicativo ou que não trazem melhorias significativas a um fluxo de trabalho não devem passar pela revisão de complementos para publicação.
Mantenha os escopos restritos
Ao definir seus escopos
explicitamente, sempre escolha o
conjunto de escopos menos permissivo possível. Por exemplo, não faça com que seu
complemento solicite acesso total ao
Calendário do usuário com o escopo
https://www.googleapis.com/auth/calendar se ele precisar apenas de acesso de leitura. Para acesso somente leitura, use o escopo
https://www.googleapis.com/auth/calendar.readonly.
Evite depender demais de bibliotecas
O uso de bibliotecas do Apps Script pode fazer com que o complemento execute mais lentamente do que se todo o código do Apps Script estivesse contido em um único projeto de script. Embora as bibliotecas do Apps Script funcionem em complementos, você pode ter reduções de performance se as usar. Evite incluir bibliotecas desnecessárias no projeto e considere maneiras de reduzir a dependência do complemento delas.
A latência descrita acima se aplica apenas a projetos do Apps Script usados como bibliotecas do lado do servidor. Você pode usar bibliotecas JavaScript do lado do cliente, como jQuery, sem encontrar essa latência.
Práticas recomendadas para complementos do Google Workspace
As práticas recomendadas a seguir se aplicam apenas aos complementos do Google Workspace e ao uso do serviço de card.
Usar apenas alguns cards
Se o complemento usar muitos cards, a configuração de navegação vai ficar complexa e difícil de gerenciar.
Evite criar mais cards do que o necessário.
Usar funções de criação de widgets
Ao escrever um código que cria um
Card ou outros objetos de interface complexos,
coloque esse código em uma função própria. Essa função de criação precisa
apenas criar e retornar o objeto. Isso permite regenerar rapidamente esse
objeto sempre que a interface precisar ser atualizada. Não se esqueça de chamar build() depois de usar
as classes de builder no serviço de card.
Simplifique os cards
Se um determinado card tiver muitos widgets, ele poderá ocupar muito espaço na tela e se tornar menos útil. Embora as seções grandes de cards sejam renderizadas como elementos de interface recolhíveis, isso oculta informações do usuário. O objetivo é simplificar o complemento e oferecer exatamente o que o usuário precisa e nada mais.
Usar cards de erro
Crie cards para condições de erro. Se o complemento produzir um erro, ele vai mostrar um card com as informações do erro e instruções sobre como corrigir o problema, se possível. Por exemplo, se o complemento não conseguir se conectar a um serviço que não é do Google porque a autorização falhou, mostre um card informando isso e peça ao usuário para verificar as informações da conta usadas.
Escrever testes e mensagens de teste
Teste todos os complementos que você criar. Crie funções de teste que criam cards e widgets usando dados de teste e verifique se os objetos são criados conforme o esperado.
Ao usar funções de retorno de chamada de ação, geralmente é necessário construir um objeto de resposta. Use declarações como as seguintes para verificar se as respostas estão sendo construídas corretamente:
Logger.log(response.printJson());
Execute as funções de teste criadas diretamente no editor do Apps Script usando o menu Executar. Quando você tiver um complemento viável funcionando, instale a versão não publicada para testá-lo.
Use dados de teste adequados para cada aplicativo host que o
complemento estende. Por exemplo, se o
complemento estender o Gmail, provavelmente você vai precisar de
alguns e-mails de teste e os IDs das mensagens para garantir que o
complemento funcione conforme o esperado quando receber diferentes
conteúdos de mensagens. Para conseguir o ID de uma mensagem, liste
as mensagens usando o método Gmail API
users.messages.list
ou o serviço
Gmail do Apps Script.
Práticas recomendadas para conferências no Google Agenda
Se o complemento integrar opções de conferência de terceiros ao Google Agenda, siga estas outras práticas recomendadas:
Mantenha a luz onCreateFunction
Cada
onCreateFunction
definido no manifesto é chamado de forma síncrona quando um usuário tenta
criar uma solução de conferência desse tipo. Verifique se essas funções fazem apenas o
trabalho mínimo necessário para criar a conferência. Fazer muito nessas
funções pode causar uma experiência lenta para o usuário do
complemento.
Usar os campos ConferenceData adequados para dados de conferência
Ao criar objetos
ConferenceData
, é possível preenchê-los com detalhes sobre a conferência (códigos de acesso,
números de telefone, PINs, URIs etc.). Use o campo EntryPoint correspondente para essas informações. Não coloque esses detalhes no campo de observações ConferenceData.
Não anexar detalhes de videoconferência ao evento da Agenda
O complemento não precisa adicionar informações sobre conferências de terceiros criadas à descrição do evento da Agenda. O Google Agenda faz isso automaticamente quando necessário.