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 dos complementos e escolha um proprietário e colaboradores.
  2. Crie o visual e o comportamento do seu complemento.
  3. Configurar o manifesto do projeto ou o recurso de implantação dos complementos.
  4. Escreva o código para definir a aparência e o comportamento do complemento.
  5. Verifique os escopos do OAuth dos complementos.
  6. Teste o complemento nos aplicativos host que ele estende.
  7. Publique o complemento.

Configure os projetos dos complementos e escolha um proprietário e colaboradores

Se você criar seu complemento no Apps Script, precisará criar um projeto do Apps Script e um projeto do Google Cloud. Se você criar seu complemento em uma linguagem diferente do 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 ter a propriedade 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 com a programação e os testes.

Projetos do Apps Script

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

Quando você publica um complemento, uma única conta de usuário atua como 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 do Cloud dos complementos. Isso ajuda a garantir que alguém da sua equipe sempre possa acessar as configurações do Cloud dos complementos.

Criar a aparência e o comportamento dos complementos

Decida como você quer que seu complemento seja e como ele deve se comportar antes de começar a criá-lo. Considere os casos de uso em que o complemento precisa tentar fornecer soluções. Comece com um design simples para começar o trabalho primeiro e depois adicione mais refinamentos.

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

Configurar o manifesto do projeto de complementos

Em projetos do Apps Script, o manifesto do projeto é um arquivo JSON especial. Ele especifica vários detalhes sobre o projeto, como as dependências da 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 dos complementos.

Programe o complemento

Você precisa implementar uma interface baseada em cartão para o complemento. Use o serviço de card do Apps Script ou, se você estiver escrevendo em outra linguagem de código, retorne um JSON formatado corretamente para que a interface seja renderizada como cartões.

Você também precisa implementar todas 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, você também vai precisar configurar o OAuth desse serviço.

Como criar cards

Para definir uma interface do usuário de complemento, crie objetos Card e os preencha com widgets. As funções de gatilho especificadas no manifesto precisam retornar um único objeto Card ou uma matriz de objetos Card que representam 'pages' diferentes 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 cards usando a classe CardBuilder. Cada card exige um CardHeader e um ou mais CardSections. Você precisa preencher cada seção do card com os widgets individuais que compõem a interface do complemento. 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 card usando o 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 os dados buscados em serviços que não são do Google.

Se o Google Workspace Complemento precisar de acesso a APIs que não são do Google que exigem OAuth, você precisará configurar e se conectar a esse serviço. Para mais detalhes, consulte o Guia de conexão com serviços de terceiros.

Ordem de construção

Ao criar um cartão, é necessário criar uma recarga de cima para baixo. Ou seja, é preciso usar esta ordem de construção:

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

Isso é necessário porque, ao adicionar um widget a uma seção de cartão ou cartão, você adiciona uma cópia desse widget. As mudanças feitas no objeto do widget após a adição não são refletidas no card final.

Ações universais

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

Consulte Ações universais para ver mais detalhes.

Verificar os escopos do OAuth do complemento

Escopos definem quais ações o complemento tem permissão para realizar em nome de um usuário. A prática recomendada é que os complementos tenham apenas escopos para ações que eles precisam ter em ordem de função e nada mais.

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

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, será possível usar o complemento na conta e testar a aparência e o comportamento nos aplicativos host estendidos. Verifique se o complemento se comporta conforme o esperado para contextos e ações do usuário.

Consulte Complementos Google Workspace de teste para mais detalhes.

Publicar o complemento

A publicação do complemento o torna disponível para outras pessoas, publicamente ou apenas para usuários no 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ído.

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

Consulte Complemento Google Workspace de publicação para ver mais detalhes.

Google Workspace Exemplo de complemento

 l10n-placeholder41=

Para ajudar você a entender como os Google Workspace complementos são criados, o Google Workspace "Cats" add-on quickstart mostra como criar um complemento Google Workspace simples, incluindo páginas iniciais, conexão de serviços, navegação de cartão e Depois de concluir o guia de início rápido, você pode instalar o complemento e testar o código.