Quando você quiser criar um novo complemento do Google Workspace, siga este procedimento geral:
- Configure os projetos do complemento e escolha um proprietário e colaboradores.
- Projete a aparência e o comportamento do seu complemento.
- Configure o manifesto do projeto ou o recurso de implantação do complemento.
- 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 o 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ário dos projetos e decidir quais outras contas sã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 codificação e os 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 de complementos 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 editor. A conta de publicação precisa ter acesso de edição ao projeto de script, mas não precisa ser a de proprietário.
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 possa sempre acessar as configurações do complemento.
Para criar um projeto do Google Cloud, consulte Criar um projeto do Google Cloud.
Projetar a aparência e o comportamento dos complementos
Decida como você quer que seu complemento seja e como ele se comportará antes de começar a criá-lo. Pense em 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 Guia de estilo de complementos do Google Workspace para ver diretrizes sobre como projetar a experiência do complemento.
Configurar o manifesto do projeto de complemento
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 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ê 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
É preciso implementar uma interface baseada em cartão para o complemento. Use o serviço Card do Apps Script ou, se você estiver escrevendo em outra linguagem de código, retorne JSON JSON formatado corretamente para renderizar a interface como cards.
Também é necessário implementar quaisquer 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á preciso configurar o OAuth para esse serviço.
Criar cards
Para definir uma interface do 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 representam diferentes "páginas" da interface de complemento. Ele também pode criar e exibir novos cards em resposta a 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. Preencha cada seção do cartão com os widgets individuais que compõem a interface complementar. 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 card usando o
CardBuilder, chame
CardBuilder.build()
para criar o objeto Card correspondente.
Você pode usar outros serviços integrados do Apps Script, como o CalendarApp, para recuperar informações que serão exibidas nos cartões complementares criados.
Você pode usar dados buscados em serviços que não são do Google.
Se os complementos do Google Workspace precisarem acessar APIs que não são do Google que exigem o OAuth, configure e conecte-se a esse serviço. Consulte o guia Como se conectar a serviços que não são do Google para ver mais detalhes.
Pedido de construção
Ao criar um cartão, é necessário criar de cima para baixo. Ou seja, você precisa usar esta ordem de construção:
- Crie o widget.
- Adicionar o widget à seção de cards.
- Repita até que a seção do card tenha todos os widgets.
- Adicione a seção do card.
Isso é necessário porque, ao adicionar um widget a um card ou uma seção de cards, você está, na verdade, adicionando uma cópia desse widget. As mudanças que você fizer no objeto de widget depois de adicioná-lo não serão refletidas no cartão final.
Ações universais
Você pode usar ações universais para fornecer funcionalidade independente do contexto. As ações universais são itens de menu disponíveis na IU 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 mais detalhes.
Verificar os escopos do complemento do OAuth
Os escopos definem quais ações o complemento pode executar em nome do usuário. É uma prática recomendada que os complementos tenham escopos apenas para as ações que eles precisam ter na função de ordem e nada mais.
Em projetos complementares, defina explicitamente os escopos do complemento para garantir que o complemento 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 hospedeiros que ele estende. Verifique se o complemento se comporta conforme o esperado para contextos e ações do usuário.
Veja mais detalhes em Testar complementos do Google Workspace.
Publicar o complemento
A publicação do complemento o torna disponível para outras pessoas, seja publicamente ou apenas pelos 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 de conclusão.
Os complementos do Google Workspace estão publicados no Google Workspace Marketplace. Os complementos disponíveis publicamente precisam passar pela revisão do app antes da publicação.
Consulte Como publicar o complemento do Google Workspace para mais detalhes.
Exemplo de complemento do Google Workspace
Para ajudar você a entender como os complementos do Google Workspace são criados, veja no Guia de início rápido do complemento Gatos do Google Workspace como criar um complemento simples do Google Workspace, incluindo páginas iniciais, navegação com cards 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.