Criar complementos do Google Workspace

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 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. HTTP endpoints: Which should you choose? 🤔" (em inglês).

Escolher aplicativos host do Google Workspace

É possível configurar 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
Google Slides

Para saber como criar 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 projeto na nuvem do Google. Se você criar o complemento em um idioma diferente do Apps Script, só será necessário criar um projeto do Google Cloud.

Antes de iniciar o desenvolvimento do complemento, escolha uma única conta de usuário para ser proprietária 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 codificação e nos testes.

Projetos do Apps Script

Antes de criar o 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 é mais adequado para o desenvolvimento leve de complementos pessoais ou internos com uma pequena base de usuários. Se você prevê a criação de um complemento em grande escala que precisa lidar com muitos usuários, exige baixa latência ou demanda controle total sobre sua infraestrutura, considere desenvolver em um ambiente de execução diferente.

É possível 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 o proprietário.

Para criar um projeto do Apps Script, consulte Projetos de script.

Projetos do Google Cloud

Recomendamos que você adicione colaboradores ao projeto na nuvem 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 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 criá-lo. Considere quais casos de uso o complemento deve tentar resolver. 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 diretrizes sobre como projetar a experiência do usuário do complemento.

Configurar o manifesto do complemento

Depois de projetar o complemento, você pode começar a implementar o design no manifesto do complemento. O manifesto é onde você configura a maior parte da aparência e do comportamento do complemento, incluindo os aplicativos host do Google Workspace que o complemento 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 Chat. Para conferir as etapas, consulte Configurar um app Google Chat.

Crie o complemento

É necessário 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 JSON formatado corretamente para que a interface seja renderizada como cards.

Você também precisa 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.

Construir cards

Você define uma interface do usuário do complemento criando Card objetos e preenchendo-os com widgets. As funções de acionador especificadas no manifesto precisam retornar um único Card objeto ou uma matriz de Card objetos que representam diferentes 'páginas' da interface do complemento. O 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 CardBuilder classe. Cada card exige um CardHeader e uma ou mais CardSections. Preencha cada seção de card com os widgets individuais que compõem a interface do complemento. 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 card 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 a serem mostradas nos cards de complementos criados. 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 que exigem o OAuth, você precisará 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.

Ordem de construção

Ao criar um card, você precisa criar de cima para baixo. Ou seja, você precisa usar 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 card, você está adicionando uma cópia desse widget. As mudanças feitas no objeto de widget depois de adicioná-lo não são refletidas no card final.

Ações universais

É possível usar ações universais para fornecer funcionalidades independentes do contexto. As ações universais são itens de menu disponíveis na interface do complemento, independentemente do card mostrado. Todas as ações universais definidas sempre aparecem no menu de cards do complemento.

Consulte Ações universais para mais detalhes.

Verificar os escopos OAuth do complemento

Escopos definem quais ações o complemento pode realizar em nome de um usuário. É recomendável que os complementos tenham apenas escopos para ações necessárias para funcionar e nada mais.

Nos 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 o complemento usa em no complemento manifesto.

Consulte Escopos para mais detalhes.

Testar o complemento

É possível testar complementos não publicados instalando-os primeiro. 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.

Para começar a testar o complemento, consulte os seguintes guias:

Publicar o complemento

A publicação do complemento o disponibiliza para outras pessoas, publicamente ou apenas para usuários do 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 concluir a análise do app antes de serem publicados.

Consulte Publicar complementos do Google Workspace para mais detalhes.