Nesta página, você encontra 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 seu complemento esteja disponível para os usuários.
- Configure os projetos do complemento e escolha um proprietário e colaboradores.
- Projete e configure a aparência e o comportamento do complemento.
- Crie o complemento.
- Verifique os escopos OAuth do complemento.
- Teste o complemento em um ou mais aplicativos do Google Workspace.
- Publique o complemento.
É possível criar um complemento com o Apps Script ou HTTP. Para uma comparação, assista ao vídeo "Apps Script vs. endpoints HTTP: qual escolher?" 🤔".
Escolher aplicativos host do Google Workspace
Você pode configurar os complementos do Google Workspace para aparecer nos seguintes aplicativos host do Google Workspace:
- Gmail
- Google Agenda
- Google Chat
- Google Docs
- Google Drive
- Google Meet
- Planilhas Google
- Apresentações Google
Para saber como criar aplicativos para o Google Workspace, consulte Estender a interface do Google Workspace.
Configurar os projetos do complemento e escolher um proprietário e colaboradores
Se você criar seu complemento no Apps Script, vai 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 começar o desenvolvimento de complementos, escolha uma única conta de usuário para ser proprietária dos projetos e decida quais outras contas serã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
Antes de criar seu complemento, revise as cotas e limitações do Apps Script para garantir que o design do projeto esteja alinhado a essas diretrizes. O Apps Script é ideal para desenvolvimento leve de complementos pessoais ou internos com uma pequena base de usuários. Se você pretende criar um complemento em grande escala que precise lidar com muitos usuários, exija baixa latência ou controle total sobre sua infraestrutura, considere desenvolver em um ambiente de tempo de execução diferente.
Você pode criar os arquivos de projeto do Apps Script do 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.
Ao publicar 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 proprietária.
Para criar um projeto do Apps Script, consulte Projetos de script.
Projetos do Google Cloud
Recomendamos que você adicione colaboradores ao projeto do complemento no Cloud. Isso ajuda a garantir que alguém da sua equipe sempre possa acessar as configurações de nuvem do complemento.
Para criar um projeto do Google Cloud, consulte Criar um projeto do Google Cloud.
Projetar e configurar a aparência e o comportamento do complemento
Decida como você quer que o complemento seja e como ele deve se comportar antes de começar a criar. Considere quais casos de uso o complemento deve tentar resolver. 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 saber como criar a experiência do usuário do complemento.
Configurar o manifesto do complemento
Depois de criar o complemento, você pode começar a implementar o design no manifesto do complemento. É no manifesto que você configura a maior parte da aparência e do comportamento do complemento, incluindo os aplicativos host do Google Workspace que ele estende.
Para mais detalhes, consulte Manifestos para complementos do Google Workspace.
À 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 do complemento.
Configurar a aparência e o comportamento do app Google Chat
Se você criou um complemento que estende o Google Chat, use a API Google Chat para configurar a aparência e o comportamento de um app do Chat. Para conferir as etapas, acesse Configurar um app do Google Chat.
Criar o complemento
Você precisa implementar uma interface baseada em cards para o complemento. Use o serviço de card do Apps Script ou, se estiver programando em outra linguagem, retorne o JSON formatado corretamente para que a interface seja renderizada como cards.
Também é necessário implementar 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 precisará configurar o OAuth para esse serviço.
Construir cards
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 mostrar novos cards em
resposta às 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. Você precisa
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 deles.
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 e mostrar nos cards do complemento que você criar.
Você pode usar dados extraídos de serviços que não são do Google.
Se o complemento precisar de acesso a APIs que não são do Google e exigem OAuth, configure e conecte-se a esse serviço. Consulte o guia de conexão com serviços que não são do Google para mais detalhes.
Pedido de construção
Ao criar um card, você precisa começar de cima para baixo. Ou seja, use esta ordem de construção:
- Crie o widget.
- Adicione o widget à seção de cards.
- Repita até que a seção de cards tenha todos os widgets.
- Adicione a seção de cartão ao card.
Isso é necessário porque, ao adicionar um widget a um card ou seção de card, você está adicionando uma cópia desse widget. As mudanças feitas no objeto do widget depois de adicionado não são refletidas no card final.
Universal Actions
É possível usar ações universais para oferecer funcionalidades independentes do contexto. As ações universais são itens de menu disponíveis na interface do complemento, independente do card mostrado. Todas as ações universais definidas sempre aparecem no menu de card do complemento.
Consulte Ações universais para 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 escopos para as ações necessárias ao funcionamento deles, e nada mais.
Em projetos de complementos, defina explicitamente os escopos do complemento para garantir que ele use o conjunto de escopos menos permissivo possível. Você define quais escopos seu complemento usa 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 host que ele estende. Verifique se o complemento se comporta como esperado para contextos e ações do usuário.
Para começar a testar seu complemento, consulte os seguintes guias:
- Testar e depurar complementos do Apps Script para o Google Workspace
- Testar e depurar complementos HTTP do Google Workspace
- Testar recursos interativos para apps do Google Chat
Publicar o complemento
Ao publicar seu complemento, ele fica disponível para outras pessoas, seja publicamente ou apenas para usuários no seu domínio. Antes de iniciar o processo de publicação, revise 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 são publicados no Google Workspace Marketplace. Os complementos disponíveis publicamente precisam passar por uma análise de app antes de serem publicados.
Consulte Publicar um complemento do Google Workspace para mais detalhes.