Práticas recomendadas

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Melhore sua experiência geral dos usuários seguindo estes guias para o complemento de complementos.

Práticas recomendadas gerais

Recomendamos que você siga as práticas recomendadas a seguir para todos os complementos desenvolvidos.

Determine a propriedade do complemento antes de começar

Os complementos são definidos por projetos do Apps Script, que precisam pertencer a uma conta específica ou colocados em um drive compartilhado. Antes de codificar um complemento, determine qual conta precisa ter a propriedade do projeto e qual conta atua como editor. Determine também quais contas devem atuar como colaboradores e verifique se essas contas têm acesso ao projeto de script e ao projeto do Cloud Platform associado.

Ampliar o Google Workspace, não replicar

Os complementos fornecem novos recursos para os aplicativos do Google Workspace que eles estendem, ou podem automatizar tarefas complexas. Complementos que são apenas funcionalidades do aplicativo ou que não fazem replicações significativas em um fluxo de trabalho provavelmente não passam na revisão de complemento para publicação.

Manter os escopos restritos

Ao definir seus escopos explicitamente, sempre escolha o conjunto menos permissivo de escopos possível. Por exemplo, não solicite o acesso completo à 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 de bibliotecas

O uso de bibliotecas do Apps Script pode fazer com que seu complemento seja executado mais lentamente do que se todos os códigos do Apps Script estivessem contidos em um único projeto de script. Embora as bibliotecas do Apps Script funcionem em complementos, é possível que ocorram reduções no desempenho caso sejam usadas. Evite incluir bibliotecas desnecessárias no projeto e considere formas de reduzir a dependência de complementos.

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, sem precisar encontrar essa latência.

Práticas recomendadas para complementos do Google Workspace

As práticas recomendadas a seguir só se aplicam aos Complementos do Google Workspace e ao uso do serviço de Card.

Usar apenas alguns cartões

Se ele estiver usando muitos cards, a configuração de navegação se tornará complexa e difícil de gerenciar.

Evite o impulso de criar mais cartões do que o necessário.

Usar funções de criação de widgets

Ao escrever 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 apenas cria o objeto e o retorna. 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 a simplicidade dos cards

Um cartão com muitos widgets pode preencher muito a tela e se tornar menos útil. Embora as seções de cards grandes sejam renderizadas como elementos de IU recolhíveis, essas ocultam informações do usuário. Tente simplificar seu complemento e fornecer exatamente o que o usuário precisa.

Usar cards de erros

Crie cards para condições de erro. Se o complemento produzir um erro, ele exibirá um card com as informações do erro e instruções sobre como corrigi-lo, se possível. Por exemplo, se não foi possível conectar seu complemento a um serviço que não seja do Google porque a autorização falhou, exiba um card com essa informação e peça ao usuário para verificar as informações da conta que estão sendo usadas.

Criar testes e mensagens de teste

Você precisa testar completamente todos os complementos criados. Crie funções de teste que criam cartões e widgets usando dados de teste e verifique se os objetos são criados conforme esperado.

Ao usar funções de callback de ação, geralmente é necessário criar um objeto de resposta. Use instruções como a seguinte para verificar se as respostas estão sendo construídas corretamente:

    Logger.log(response.printJson());

Execute funções de teste que você cria diretamente no editor do Apps Script usando o menu Run. Quando você tiver um complemento viável, 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, você provavelmente precisará de alguns e-mails de teste e IDs de mensagens para garantir que funcione conforme esperado ao receber conteúdo de mensagem diferente. Você pode conseguir o ID de uma mensagem específica 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 Agenda

Se o complemento integrar as opções de videoconferências de terceiros no Google Agenda, siga estas práticas recomendadas:

Manter a luz onCreateFunction

Cada onCreateFunction que você define no manifesto é chamado de forma síncrona quando um usuário tenta criar uma solução de videoconferência desse tipo. Confirme se essas funções realizam o trabalho mínimo necessário para criar a videoconferência. Fazer muitas coisas nessas funções pode causar uma experiência lenta do usuário para seu complemento.

Usar campos ConferenceData adequados para dados de 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 correspondente EntryPoint 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

Seu complemento não precisa incluir informações sobre videoconferências de terceiros criadas na descrição do evento do Google Agenda. O Google Agenda faz isso automaticamente quando necessário.