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 para todos os complementos que desenvolver.
Determinar a propriedade do complemento antes de começar
Os complementos 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 conta atua como 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 do Google Cloud associado.
Amplie o Google Workspace, não o replique
Os complementos fornecem 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 revisão 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 peça
acesso total ao complemento do
Google Agenda 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 no desempenho se usá-las. 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 que são 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.
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 código que cria um
Card ou outros objetos de interface complexos,
coloque esse código na própria função. Essa função de criação precisa
apenas criar o objeto e o retornar. 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 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. Tenha como objetivo simplificar seu 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 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. É possível usar 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, provavelmente você precisará de alguns
e-mails de teste e os 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
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 os campos ConferenceData apropriados 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 da videoconferência ao evento da Agenda
Seu complemento não precisa adicionar informações sobre videoconferências de terceiros criadas à descrição do evento da Agenda. O Agenda faz isso automaticamente quando necessário.