Práticas recomendadas

Melhore a experiência geral dos usuários seguindo estes guias de design de complementos.

Práticas recomendadas gerais

Siga as práticas recomendadas abaixo 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 pertencer a uma conta específica ou ser colocados em um drive compartilhado. Antes de codificar um complemento, determine qual conta será proprietária do projeto e qual conta atuará como a de editora. Determine também quais contas vão atuar como colaboradores e verifique se essas contas têm acesso ao projeto de script e ao projeto do Cloud Platform associado.

Estender o Google Workspace, não replicá-lo

os complementos oferecem novos recursos aos aplicativos do Google Workspace que eles estendem ou automatizam tarefas complexas. Os complementos que simplesmente replicam a funcionalidade que já está no aplicativo ou aqueles que não fazem melhorias significativas no fluxo de trabalho provavelmente não serão aprovados na avaliação de complementos para publicação.

Manter os escopos restritos

Ao definir seus escopos explicitamente, sempre escolha o conjunto menos permissivo possível. Por exemplo, não tenha a solicitação do complemento de acesso total à agenda do usuário com o escopo https://www.googleapis.com/auth/calendar se ela precisar apenas de acesso de leitura. Para acesso somente leitura, use o escopo https://www.googleapis.com/auth/calendar.readonly.

Evitar depender demais das bibliotecas

Com o uso das bibliotecas do Apps Script, seu complemento pode ser executado mais lentamente do que seria 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, elas podem ser reduzidas no desempenho. Evite incluir bibliotecas desnecessárias no projeto e considere maneiras de reduzir a dependência delas pelo complemento.

A latência descrita acima só se aplica a projetos do Apps Script usados como bibliotecas do lado do servidor. É possível usar bibliotecas JavaScript do lado do cliente, como o jQuery, de maneira livre, sem essa latência.

Práticas recomendadas dos 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 cards.

Usar apenas alguns cards

Se o complemento usar muitos cards, a configuração de navegação ficará 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 um código que crie Card ou outros objetos de IU complexos, coloque esse código em uma função própria. Essa função cria e retorna o objeto. Isso permite gerar 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.

Simplifique os cards

Se um determinado card tiver muitos widgets, ele poderá preencher muito da tela e se tornar menos útil. Embora as seções grandes de cards sejam renderizadas como elementos de IU recolhíveis, isso oculta as informações do usuário. Procure 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 exibirá 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 puder se conectar a um serviço que não seja do Google porque a autorização falhou, mostre um cartão informando isso e peça ao usuário para verificar as informações da conta que estão sendo usadas.

Criar testes e mensagens de teste

É preciso testar completamente todos os complementos criados. Crie funções de teste que criem cards e widgets usando dados de teste e, em seguida, verifique se os objetos foram criados conforme o esperado.

Ao usar funções de callback de ação, geralmente você precisa criar um objeto de resposta. É possível 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 em funcionamento, instale a versão não publicada para testá-la.

Usar os dados de teste apropriados 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 códigos de mensagem deles para garantir que o complemento funcione conforme esperado quando um conteúdo de mensagem diferente for fornecido. Para conseguir o ID de uma determinada mensagem, liste-as com o método Users.messages.list da API Gmail ou com o serviço do Gmail do Apps Script.

Práticas recomendadas para videoconferências no Google Agenda

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

Manter a onCreateFunction lâmpada

Cada onCreateFunction definido no manifesto é chamado de maneira síncrona quando um usuário tenta criar uma solução de videoconferência desse tipo. Verifique se essas funções fazem apenas o trabalho mínimo necessário para criar a conferência. Excesso dessas funções pode causar uma experiência do usuário lenta no complemento.

Use os campos ConferenceData apropriados 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 EntryPoint correspondente para essas informações. Não insira esses detalhes no campo de notas ConferenceData.

Não anexar detalhes da 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.