Esta página oferece uma visão geral de como projetar, criar e publicar complementos do Google Workspace. Esta visão geral explica as seguintes etapas:
- Determine os aplicativos do Google Workspace em que você quer que o complemento esteja disponível para os usuários.
- 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 OAuth do seu complemento.
- Teste o complemento em um ou mais aplicativos do Google Workspace.
- Publique o complemento.
Escolher aplicativos do Google Workspace como host
É possível configurar os complementos do Google Workspace para aparecerem nos seguintes aplicativos host do Google Workspace:
- Gmail
- Google Agenda
- Documentos Google
- Google Drive
- Planilhas Google
- Apresentações Google
Para saber como criar para aplicativos do Google Workspace, consulte Estender a interface do Google Workspace.
Configurar os projetos do complemento e escolher um proprietário e colaboradores
Se você criar o complemento no Apps Script, vai criar um projeto do Apps Script e um 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 do complemento, escolha uma única conta de usuário para ser o proprietário dos projetos e decida 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 nos 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 possa sempre acessar as configurações do complemento no Cloud.
Para criar um projeto do Google Cloud, consulte Criar um projeto do Google Cloud.
Projetar a aparência e o comportamento do complemento
Defina como você quer que seu complemento seja e como ele vai 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 depois 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 do complemento
Nos projetos do Apps Script, o manifesto do projeto é um arquivo JSON especial. Ele especifica vários 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 de 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ódigos e recursos ao seu 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 de cards do Apps Script ou, se estiver escrevendo em outro idioma de código, retorne um JSON formatado corretamente para que a interface seja renderizada como cards.
Você também precisa implementar todas as funções de gatilho 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.
Cartas de construção
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 representem
diferentes "páginas" 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. É necessário
preencher cada seção de 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 usando o
CardBuilder, 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.
É possível usar dados buscados de serviços de terceiros.
Se o complemento precisar de acesso a APIs que não são do Google que exigem 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 mais detalhes.
Ordem de construção
Ao criar um card, você precisa começar 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 card tenha todos os widgets.
- Adicione a seção do card ao card.
Isso é necessário porque, ao adicionar um widget a um card ou seção de cards, você está adicionando uma cópia dele. As mudanças feitas no objeto do widget depois de adicioná-lo não sã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 do card exibido. Todas as ações universais definidas aparecem sempre no menu do card do complemento.
Consulte Ações universais para ver mais detalhes.
Verificar os escopos do 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 apenas os escopos de ações que precisam ter para funcionar e nada mais.
Em projetos de complementos, defina explicitamente os escopos de complemento para garantir que o complemento use o conjunto de escopos menos permissivo possível. Você define quais escopos seu complemento usa no manifesto do complemento.
Consulte Escopos para mais detalhes.
Testar o complemento
Para testar complementos não publicados, 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 amplia. Verifique se o complemento se comporta como 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, leia 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 Publicar um complemento do Google Workspace para mais detalhes.