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 do complemento e escolher um proprietário e colaboradores
Se você criar seu complemento no Apps Script, 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 ser proprietária dos projetos e decidir quais outras contas serão colaboradoras. 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 do projeto do Apps Script em um drive compartilhado para que nenhuma conta seja de propriedade exclusiva. Colocar o arquivo de script do complemento em um drive compartilhado garante que vários colaboradores 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 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 tenha acesso às 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 a aparência e o comportamento do complemento antes de começar a criá-lo. Considere para quais casos de uso o complemento deve tentar fornecer soluções. Comece com um design simples para começar a funcionar primeiro e, em seguida, adicione mais refinamentos.
Consulte o Guia de estilo de complementos do Google Workspace para orientações sobre como criar a experiência do usuário do seu complemento.
Configurar o manifesto do projeto de complemento
Em projetos do Apps Script, o manifesto do projeto é um arquivo JSON especial. Ele especifica uma variedade de detalhes sobre o projeto, como as dependências de biblioteca. Para 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.
À medida que você adicionar 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
Você precisa implementar uma interface baseada em cards para o complemento. Use o serviço Card do Apps Script ou, se você estiver escrevendo em outra linguagem de código, retorne o JSON corretamente formatado para a interface renderizar como cards.
Também é necessário implementar todas as funções de acionador 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 precisará configurar o OAuth para esse serviço.
Criar cards
Para definir uma interface do usuário de um complemento, crie objetos
Card e preencha-os com
widgets. As funções de acionamento especificadas no
manifesto precisam retornar um único objeto
Card ou uma matriz de objetos
Card que representam 'páginas' diferentes da interface do complemento. Seu
complemento também pode criar e mostrar novos cards em
resposta a 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. Preencha cada seção do cartão com os widgets individuais que compõem a interface do complemento. Os widgets de
interação, geralmente estão
vinculados a ações para definir
o comportamento de interação.
Depois de adicionar todas as seções e widgets ao seu card usando o
CardBuilder dele, chame
CardBuilder.build()
para criar o objeto Card correspondente.
É possível usar outros serviços integrados do Apps Script, como CalendarApp, para recuperar informações que serão exibidas nos cards de complementos criados.
Você pode 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, 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.
Ordem de construção
Ao criar um cartão, você precisa construir a partir do topo. Ou seja, use esta ordem de construção:
- Crie o widget.
- Adicione o widget à seção do card.
- Repita até que a seção do cartão tenha todos os widgets.
- Adicione a seção do cartão ao card.
Isso é necessário porque, ao adicionar um widget a uma seção de cartões ou cartões, na verdade, você adiciona uma cópia desse widget. As mudanças feitas no objeto do widget após adicioná-lo não serão refletidas no card final.
Ações universais
Use ações universais para fornecer funcionalidades independentes de contexto. As ações universais são itens de menu disponíveis na interface do complemento, independentemente de qual cartão é exibido. Todas as ações universais definidas sempre aparecem no menu do card do complemento.
Consulte Ações universais para ver mais detalhes.
Verifique os escopos do OAuth do complemento
Os escopos definem quais ações o complemento tem permissão para realizar em nome de um usuário. É uma prática recomendada que os complementos tenham escopos apenas para as ações necessárias para a ordem 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 manifesto do complemento.
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 que ele estende. Verifique se o complemento se comporta conforme esperado para contextos e ações do usuário.
Consulte Como testar complementos do Google Workspace para mais detalhes.
Publicar o complemento
A publicação do seu complemento o disponibiliza para outras pessoas, seja publicamente ou apenas usuários 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 exige preparação e tempo para ser concluído.
Os complementos do Google Workspace foram publicados no Google Workspace Marketplace. Os complementos disponíveis publicamente precisam passar pela revisão do app antes de serem publicados.
Consulte Como publicar complemento do Google Workspace para mais detalhes.