Para criar um novo complemento do Google Workspace, siga este procedimento geral:
- Configure os projetos do complemento e escolha um proprietário e colaboradores.
- Crie a aparência e o comportamento do complemento.
- Configure o manifesto do projeto do complemento ou o recurso de implantação.
- Escreva o código para definir a aparência e o comportamento do complemento.
- Verifique os escopos do OAuth do complemento.
- Teste o complemento nos aplicativos host que ele estende.
- Publique o complemento.
Configurar os projetos dos complementos e escolher um proprietário e colaboradores
Se criar seu complemento no Apps Script, você criará um projeto do Apps Script e um projeto do Google Cloud. Se você criar seu complemento em uma linguagem diferente do Apps Script, basta 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 serão colaborativas. O proprietário cria e gerencia os arquivos do projeto e as configurações associadas, enquanto os colaboradores podem ajudar na programação e nos testes.
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 propriedade exclusiva. Colocar o arquivo de script do complemento em um drive compartilhado garante que vários colaboradores tenham acesso ao projeto de script.
Quando você publica um complemento, uma única conta de usuário atua como o editor. A conta de publicação precisa ter acesso para editar o projeto de script, mas não precisa ser a proprietária.
Para criar um projeto do Apps Script, consulte Projetos do Script.
Projetos do Google Cloud
Recomendamos que você adicione colaboradores ao projeto do Cloud do complemento. Isso ajuda a garantir que alguém da sua equipe sempre possa acessar as configurações do Cloud do complemento.
Para criar um projeto do Google Cloud, consulte Criar um projeto do Google Cloud.
Projetar a aparência e o comportamento do complemento
Decida qual será a aparência do complemento e como ele deve se comportar antes de começar a criá-lo. Pense em para quais casos de uso o complemento precisa tentar fornecer soluções. Comece com um design simples para começar e depois adicione mais refinamentos.
Consulte o Guia de estilo de complementos do Google Workspace para ver diretrizes sobre como criar a experiência do usuário de 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 os complementos do Google Workspace, 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.
Ao adicionar código e recursos ao complemento, edite o manifesto conforme necessário para produzir a aparência e o comportamento necessários.
Programar o complemento
Implemente uma interface baseada em cartão para o complemento. Use o serviço Card do Apps Script ou, se estiver escrevendo em outra linguagem de código, retorne o JSON formatado corretamente para que a interface seja renderizada como cards.
Também é necessário implementar qualquer função de acionador especificada no manifesto do complemento. Se o complemento se conectar a um serviço de terceiros que não seja do Google usando OAuth, também será necessário configurar o OAuth para esse serviço.
Cards de construção
Para definir uma interface do usuário de complemento, crie
objetos Card e preencha-os com
widgets. As funções de gatilho especificadas no
manifesto precisam retornar um único objeto
Card ou uma matriz de objetos
Card que representam
diferentes "páginas" da interface do complemento. Seu complemento também pode criar e exibir novos cartões em resposta a ações do usuário.
No Apps Script, você cria cards usando a classe
CardBuilder. Cada
card requer um CardHeader
e um ou mais
CardSections. Preencha
cada seção do card com os widgets individuais que compõem a
interface do complemento. Os 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 pelo
CardBuilder, chame
CardBuilder.build()
para criar o objeto Card correspondente.
É possível usar outros serviços integrados do Apps Script,
como o
CalendarApp, para recuperar
informações que vão ser mostradas nos cards de complementos que você criar.
usar dados buscados em serviços de terceiros;
Se os complementos do Google Workspace precisarem de acesso a APIs que não são do Google que exigem OAuth, será necessário configurar e se conectar 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 cartão, você precisa começar da recarga. Ou seja, é necessário usar esta ordem de construção:
- Crie o widget.
- Adicione o widget à seção do cartão.
- Repita até que a seção do cartão tenha todos os widgets.
- Adicione a seção do cartão ao cartão.
Isso é necessário porque, ao adicionar um widget a uma seção de cartão ou cartão, na verdade você está adicionando uma cópia desse widget. As mudanças feitas no objeto de widget após adicioná-lo não são refletidas no card final.
Ações universais
É possível usar ações universais para fornecer uma funcionalidade independente do contexto. Ações universais são itens de menu disponíveis na IU do complemento, independente do card mostrado. Todas as ações universais definidas sempre aparecem no menu do card do complemento.
Consulte Ações universais para mais detalhes.
Verificar os escopos OAuth do complemento
Os escopos definem quais ações o complemento pode realizar em nome de um usuário. É uma prática recomendada que os complementos tenham escopos apenas para as ações que precisam ter na ordem correta e nada mais.
Em projetos complementares, defina explicitamente os escopos do complemento para garantir que o complemento use o conjunto menos permissivo de escopos possível. Você define os escopos usados no complemento no manifesto.
Consulte Escopos para ver mais detalhes.
Testar o complemento
Para testar os 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 que ele estende. Verifique se o complemento se comporta conforme o esperado para contextos e ações do usuário.
Veja mais detalhes em Como testar complementos do Google Workspace.
Publicar o complemento
Ao publicar seu complemento, ele fica disponível para outras pessoas, publicamente ou apenas para usuários do 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ído.
Os complementos do Google Workspace são publicados no Google Workspace Marketplace. Os complementos disponíveis publicamente precisam passar pela revisão do app antes de serem publicados.
Consulte Como publicar o complemento do Google Workspace para saber mais.