Criar complementos do Google Workspace

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

Quando quiser criar um novo Google Workspace complemento, siga este procedimento geral:

  1. Configure os projetos do complemento e escolha um proprietário e colaboradores.
  2. Crie a aparência e o comportamento do seu complemento.
  3. Configure o manifesto do projeto do complemento ou o recurso de implantação.
  4. Escreva o código para definir a aparência e o comportamento do complemento.
  5. Verificar os escopos do OAuth do complemento.
  6. Teste o complemento nos aplicativos host que ele estende.
  7. Publique o complemento.

Configurar os projetos do complemento e escolher um proprietário e colaboradores

Se você criar um complemento no Apps Script, criará um projeto do Apps Script e do Google Cloud. Se você criar um complemento em outra linguagem que não seja o Apps Script, só precisará criar um projeto do Google Cloud.

Antes de iniciar o desenvolvimento de complementos, escolha uma única conta de usuário para ser proprietária dos projetos e decidir quais outras contas são colaboradores. O proprietário dos projetos cria e gerencia os arquivos do projeto e as configurações associadas, enquanto os colaboradores podem ajudar na programação e teste.

Projetos do Apps Script

Você pode criar os arquivos de projeto do Apps Script do seu complemento em um drive compartilhado para que nenhuma conta tenha a propriedade exclusiva. Colocar o arquivo de script de complementos em um drive compartilhado permite garantir que vários colaboradores sempre tenham acesso ao projeto de script.

Quando você publica um complemento, uma única conta de usuário atua como a do editor. A conta de publicação precisa ter acesso para edição ao projeto de script, mas não precisa ser o proprietário.

Projetos do Google Cloud

Recomendamos que você adicione colaboradores ao projeto de nuvem do complemento. Isso ajuda a garantir que alguém da sua equipe sempre possa acessar as configurações de nuvem do complemento.

Projetar a aparência e o comportamento dos complementos

Decida qual será a aparência do complemento e como ele deve se comportar antes de começar a criá-lo. Considere para quais casos de uso o complemento precisa tentar fornecer soluções. Comece com um design simples para começar a trabalhar e, em seguida, adicione mais refinamentos.

Consulte o Google Workspace guia de estilo de complementos para ver diretrizes sobre como projetar a experiência do usuário em complementos.

Configurar o manifesto do projeto de complementos

Em projetos do Apps Script, o manifesto do projeto é um arquivo JSON especial. Ela especifica vários detalhes sobre o projeto, como as dependências de biblioteca. Para Google Workspace Complementos, o manifesto também fornece as informações básicas que o aplicativo host precisa para exibir o complemento corretamente.

Consulte Manifestos para ver detalhes sobre como configurar o manifesto do seu complemento no Apps Script.

À medida que você adiciona código e recursos ao complemento, edite o manifesto conforme necessário para produzir a aparência e o comportamento necessários.

Codificar o complemento

É necessário implementar uma interface baseada em cartão para o complemento. Use o serviço de cartões do Apps Script. Se você estiver escrevendo em outra linguagem de código, retorne o JSON formatado corretamente para que a interface seja renderizada como cartões.

Também é necessário implementar as funções de acionamento especificadas no manifesto do complemento. Se o complemento se conectar a um serviço de terceiros que não seja do Google usando o OAuth, também será necessário configurar o OAuth para esse serviço.

Como criar cards

Para definir uma interface de usuário de complemento, crie objetos Card e os preencha com widgets. As funções de acionador especificadas no manifesto precisam retornar um único objeto Card ou uma matriz de objetos Card que representem diferentes "páginas" da interface do complemento. Seu complemento também pode criar e exibir novos cards em resposta às ações do usuário.

No Apps Script, você cria cartões usando a classe CardBuilder. Cada cartão requer um CardHeader e um ou mais CardSections. Você precisa preencher cada seção de card com os widgets individuais que compõem a interface complementar. Widgets de interação, geralmente são vinculados a ações para definir o comportamento de interação.

Depois de adicionar todas as seções e widgets ao cartão usando CardBuilder, chame CardBuilder.build() para criar o objeto Card correspondente.

Você pode usar outros serviços integrados do Apps Script, como CalendarApp, para recuperar informações a serem exibidas nos cartões complementares criados. É possível usar dados buscados em serviços que não são do Google.

Se seu Google Workspace complemento precisar de acesso a APIs de terceiros que exigem OAuth, configure e se conecte a esse serviço. Consulte o guia Como se conectar a serviços que não são do Google para mais detalhes.

Pedido de construção

Ao criar um card, você precisa criar de cima para baixo. Ou seja, é preciso usar esta ordem de construção:

  1. Crie o widget.
  2. Adicionar o widget à seção do card
  3. Repita até que a seção do card tenha todos os widgets dele.
  4. Adicione a seção do cartão.

Isso é necessário porque, ao adicionar um widget a um card ou a uma seção de cards, você adiciona uma cópia desse widget. As mudanças feitas no objeto do widget depois de adicioná-lo não aparecerão no card final.

Ações universais

É possível usar ações universais para fornecer funcionalidades independentes de contexto. As ações universais são itens de menu disponíveis na IU do complemento, independentemente do cartão mostrado no momento. Todas as ações universais definidas sempre aparecem no menu do card do complemento.

Consulte Ações universais para ver mais detalhes.

Verificar os escopos do OAuth do complemento

Escopos define quais ações o complemento pode realizar em nome de um usuário. É uma prática recomendada que os complementos tenham apenas escopos para as ações que eles precisam ter em ordem de funcionamento.

Em projetos de complementos, defina explicitamente os escopos do complemento para garantir que ele use o conjunto de escopos menos permissivo possível. Você define os escopos usados pelo complemento no manifesto dele.

Consulte Escopos para mais detalhes.

Testar o complemento

Para testar complementos não publicados, primeiro instale o complemento não publicado. Depois de instalado e autorizado, você pode usar o complemento na sua conta e testar a aparência e o comportamento dele nos aplicativos host estendidos. Verifique se o complemento se comporta conforme o esperado para contextos e ações do usuário.

Consulte Testes Google Workspace Complementos para mais detalhes.

Publicar o complemento

A publicação do complemento o disponibiliza para outras pessoas, publicamente ou apenas no seu domínio. Antes de iniciar o processo de publicação, consulte a visão geral da publicação. A publicação é um processo complexo que requer preparação e tempo para ser concluída.

Google Workspace Os complementos são publicados no Google Workspace Marketplace. Os complementos disponíveis publicamente precisam concluir a avaliação do app antes da publicação.

Consulte Complemento Google Workspace Publishing para mais detalhes.

Google Workspace Exemplo de complemento

 Barra lateral de complementos doGoogle Workspace

Para ajudar você a entender como os Google Workspace complementos são criados, o Google Workspace guia de início rápido do complemento Cats mostra como criar um complemento Google Workspacesimples, incluindo páginas iniciais, navegação com cartões e conexões com um serviço de terceiros. Depois de concluir o guia de início rápido, instale o complemento e teste o código.