Melhore a experiência geral do usuário seguindo estes guias para o design de complementos.
Práticas recomendadas gerais
Recomendamos que você siga as práticas recomendadas a seguir para todos os complementos desenvolvidos.
Determinar 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 de um drive compartilhado. Antes de programar um complemento, determine qual conta deve ter o projeto e qual conta atua como editor. Determine também quais contas devem atuar como colaboradores e se elas têm acesso ao projeto de script e ao projeto do Cloud Platform associado.
Ampliar o Google Workspace, não replicar
Os complementos oferecem novos recursos aos aplicativos do Google Workspace que estendem ou automatizam tarefas complexas. Os complementos que simplesmente replicam funcionalidades já presentes no aplicativo ou que não fazem melhorias significativas em um fluxo de trabalho não passam na avaliação dos complementos para publicação.
Manter os escopos restritos
Ao definir explicitamente os escopos,
sempre escolha o conjunto de permissões menos permissivo possível. Por exemplo, não
faça sua solicitação de complemento com acesso total à 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.
Evitar depender demais de bibliotecas
O uso de bibliotecas do Apps Script pode fazer com que seu complemento seja executado mais lentamente do que se todo o código do Apps Script estivesse incluído em um único projeto de script. Embora as bibliotecas do Apps Script funcionem em complementos, é possível que ocorram reduções de desempenho se forem usadas. Evite incluir bibliotecas desnecessárias no projeto e considere maneiras de reduzir a dependência do complemento neles.
A latência descrita acima se aplica apenas aos projetos do Apps Script usados como bibliotecas do lado do servidor. É possível usar bibliotecas JavaScript do lado do cliente, como jQuery, livremente, 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 cartões
Se o complemento usar muitos cards, a configuração de navegação se tornará complexa e difícil de gerenciar.
Evite o impulso de criar mais cards do que o necessário.
Usar as funções de criação de widgets
Ao escrever um código que cria Card
ou outros objetos de IU complexos, considere colocar esse código em uma função própria.
Essa função de criação só deve criar o objeto e retorná-lo. Isso permite
que você gere novamente esse objeto rapidamente sempre que a IU precisar ser atualizada. Lembre-se
de chamar build() depois de usar as classes do builder no
serviço de cartão.
Manter os cards simples
Se um determinado card tem muitos widgets, ele pode preencher muita tela e se tornar menos útil. Enquanto as seções de cards grandes são renderizadas como elementos de IU recolhíveis, isso oculta as informações do usuário. Tente simplificar seu complemento e fornecer exatamente o que o usuário precisa.
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, exiba um card informando isso e peça ao usuário para verificar as informações da conta que estão sendo usadas.
Gravar testes e mensagens de teste
Teste todos os complementos criados. Crie funções de teste que criem cartões 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 a seguir para verificar se as respostas estão sendo criadas corretamente:
Logger.log(response.printJson());
Use o menu Executar para executar as funções de teste criadas diretamente no editor do Apps Script. Quando um complemento viável funcionar, instale a versão não publicada para testá-lo.
Use os dados de teste adequados para cada aplicativo host que o complemento estende. Por exemplo, se o complemento estender o Gmail, você provavelmente precisará de alguns e-mails de teste e os IDs de mensagem para garantir que ele funcione conforme o esperado quando o conteúdo da mensagem for diferente. Você pode receber o ID de uma determinada mensagem listando mensagens com 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 do Google Agenda
Se o complemento integrar as opções de videoconferências da agenda de terceiros ao Google Agenda, siga estas práticas recomendadas:
Manter a luz do onCreateFunction
Cada onCreateFunction
definido no manifesto é chamado de forma síncrona quando um usuário tenta
criar uma solução de videoconferência desse tipo. Verifique se essas funções realizam o
trabalho mínimo necessário para criar a videoconferência. O excesso de funções
pode causar uma experiência lenta para o complemento.
Usar campos ConferenceData adequados para os dados da videoconferência
Ao criar objetos
ConferenceData,
é possível preenchê-los com detalhes sobre a videoconferê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 do Google Agenda
O complemento não precisa adicionar informações sobre videoconferências de terceiros criadas à descrição do evento do Google Agenda. O Google Agenda faz isso automaticamente quando necessário.