Melhore a experiência geral dos usuários seguindo estes guias para o design de complementos.
Práticas recomendadas gerais
Recomendamos que você siga as práticas recomendadas abaixo para todos os complementos que desenvolver.
Determinar a propriedade do complemento antes de começar
são definidos por projetos do Apps Script, que precisam ser de uma conta específica ou colocados em um drive compartilhado. Antes de programar um complemento, determine qual conta será proprietária do projeto e qual será o editor. Determine também quais contas vão atuar como colaboradoras e verifique se elas têm acesso ao projeto do script e ao projeto da plataforma do Cloud associado.
Amplie o Google Workspace, não o replique
Os complementos têm o objetivo de oferecer novos recursos aos aplicativos do Google Workspace que eles estendem ou automatizam tarefas complexas. Os complementos que apenas replicam a funcionalidade já existente no aplicativo ou que não fazem melhorias significativas em um fluxo de trabalho provavelmente não serão aprovados na análise de complementos para publicação.
Manter os escopos restritos
Ao definir seus escopos explicitamente,
sempre escolha o conjunto de escopos menos permissivo possível. Por exemplo, não
permita que o 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 muito das bibliotecas
O uso de bibliotecas do Apps Script pode fazer com que o complemento seja executado 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 uma redução de desempenho se as usar. Evite incluir bibliotecas desnecessárias no seu 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. É possível usar bibliotecas JavaScript do lado do cliente, como o 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 cartão.
Use 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 código que cria Card
ou outros objetos de interface complexos, considere colocar esse código na própria função.
Essa função de criação precisa apenas criar o objeto e o retornar. Isso permite
que você regenere 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 cartão.
Mantenha os cards simples
Se um card tiver muitos widgets, ele poderá ocupar muito da tela e tornar-se menos útil. Embora as seções de cards grandes sejam renderizadas como elementos de interface colapsáveis, isso oculta informações do usuário. O objetivo é simplificar o complemento e fornecer exatamente o que o usuário precisa e nada mais.
Usar cards de erro
Crie cards para condições de erro. Se o complemento gerar um erro, ele vai exibir um card com informações sobre o erro e instruções sobre como corrigi-lo, se possível. Por exemplo, se o complemento não conseguir se conectar a um serviço que não seja 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 que estão sendo usadas.
Programar testes e mensagens de teste
Teste todos os complementos que você criar. Crie funções de teste que criem cards e widgets usando dados de teste e verifique se os objetos são criados conforme o esperado.
Ao usar funções de callback de ação, geralmente é necessário criar um objeto de resposta. Use instruções como esta para verificar se as respostas estão sendo criadas corretamente:
Logger.log(response.printJson());
Execute funções de teste criadas diretamente no editor do Apps Script usando o menu Run. 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, é provável que você precise de alguns e-mails de teste e dos IDs das mensagens para garantir que o complemento funcione conforme o esperado com diferentes conteúdos de mensagem. É possível conferir o ID de uma mensagem específica listando mensagens usando o método Users.messages.list da API Gmail ou usando o serviço do Gmail do Apps Script.
Práticas recomendadas para videoconferências de agenda
Se o complemento integrar opções de videoconferência de agenda de terceiros ao Google Agenda, siga estas práticas recomendadas:
Mantenha a onCreateFunction acesa
Cada onCreateFunction
definida no manifesto é chamada de forma síncrona quando um usuário tenta
criar uma solução de conferência desse tipo. Confira 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 de usuário lenta para seu complemento.
Use 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, pinos, URIs etc.). Use o campo
EntryPoint
correspondente para essas informações. Não coloque esses detalhes no campo de notas
ConferenceData.
Não anexar detalhes de videoconferência ao evento do Google Agenda
Seu complemento não precisa adicionar informações sobre conferências de terceiros criadas à descrição do evento do Google Agenda. O Google Agenda faz isso automaticamente quando necessário.