Melhore a experiência geral dos usuários seguindo estes guias de design de complementos.
Práticas recomendadas gerais
Recomendamos que você use as seguintes práticas recomendadas para 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 será proprietária do projeto e qual atuará 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 a ele.
Amplie o Google Workspace, não o replique
Os complementos são destinados a oferecer novos recursos aos aplicativos do Google Workspace que eles ampliam ou automatizar tarefas complexas. Os complementos que apenas replicam funcionalidades já presentes no aplicativo ou que não fazem melhorias significativas em um fluxo de trabalho provavelmente não vão passar pela análise 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 à Agenda do usuário com o escopo https://www.googleapis.com/auth/calendar se ele só precisar de acesso de leitura. Para acesso somente leitura, use o escopo https://www.googleapis.com/auth/calendar.readonly.
Evite depender muito de 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 reduções 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 só se aplica a projetos do Apps Script usados como bibliotecas do lado do servidor. Você pode usar bibliotecas JavaScript do lado do cliente, como o jQuery, livremente sem encontrar essa latência.
Práticas recomendadas de complementos do Google Workspace
As práticas recomendadas a seguir se aplicam apenas aos complementos do Google Workspace e ao uso do serviço Card.
Use apenas alguns cards
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.
Use funções de criação de widgets
Ao escrever um código que cria um
Card ou outros objetos de interface complexos,
considere colocar esse código em uma função própria. Essa função de criação só precisa criar o objeto e retorná-lo. Isso permite que você regenere rapidamente esse objeto sempre que a interface precisar ser atualizada. Lembre-se de chamar build() depois de usar
as classes do builder no serviço Card.
Mantenha os cards simples
Se um card tiver muitos widgets, ele poderá ocupar muito espaço na tela e se tornar menos útil. Embora as seções de cards grandes sejam renderizadas como elementos de interface recolhíveis, isso oculta informações do usuário. Procure simplificar seu complemento e fornecer exatamente o que o usuário precisa e nada mais.
Use cards de erro
Crie cards para condições de erro. Se o complemento produzir um erro, ele deverá mostrar um card com as informações de 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 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.
Escreva 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, em seguida, verifique se os objetos são criados conforme o esperado.
Ao usar funções de callback de ação, geralmente é necessário construir um objeto de resposta. Você pode usar instruçõ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 publicadapara poder 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 dos IDs de mensagens para garantir que o complemento funcione conforme o esperado quando receber conteúdo de mensagens diferentes. Você pode receber o ID de mensagem de uma determinada mensagem listando
mensagens usando o método da API Gmail
users.messages.list, ou usando o serviço do Gmail
do Apps Script.
Práticas recomendadas de videoconferências do Google Agenda
Se o complemento integrar opções de videoconferência de terceiros ao Google Agenda, siga estas práticas recomendadas adicionais:
Mantenha sua onCreateFunction iluminação
Cada
onCreateFunction
definida no manifesto é chamada de forma síncrona quando um usuário tenta
criar uma solução de videoconferência desse tipo. Verifique se essas funções só fazem o trabalho mínimo necessário para criar a videoconferência. Fazer muito nessas funções pode causar uma experiência lenta para o usuário do complemento.
Use campos ConferenceData adequados para dados de videoconferência
Ao criar
ConferenceData
objetos, você pode 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 anexe detalhes da 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.