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:

1. Determine os aplicativos do Google Workspace em que você quer que o complemento esteja disponível para os usuários.
2. Configure os projetos do complemento e escolha um proprietário e colaboradores.
3. Projete e configure a aparência e o comportamento do seu complemento.
4. Crie o complemento.
5. Verifique os escopos OAuth do seu complemento.
6. Teste o complemento em um ou mais aplicativos do Google Workspace.
7. Publique o complemento.

Escolher aplicativos do Google Workspace como host

É possível configurar complementos do Google Workspace para aparecer nos seguintes aplicativos de host do Google Workspace:

• Gmail
• Google Agenda
• Google Chat (pré-lançamento para desenvolvedores)
• 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 um idioma diferente do Apps Script, só vai 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 com a programação e os testes.

Aviso: se você não adicionar colaboradores aos seus projetos de complemento, é essencial transferir a propriedade deles antes que a conta do proprietário seja encerrada ou removida. Caso contrário, você pode perder o acesso ao código e às configurações do complemento.

Projetos do Apps Script

É possível 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 do complemento em um drive compartilhado garante que vários colaboradores tenham acesso ao projeto do script.

Quando você publica um complemento, uma conta de usuário único atua como o editor. A conta de publicação precisa ter acesso de edição ao projeto do 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 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 e configurar 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.

Dica:comece com um card da página inicial simples e adicione mais widgets, cards, navegação e outros comportamentos. Você também pode considerar cards contextuais acionados por uma ação do usuário no aplicativo host, como abrir uma linha de mensagens do Gmail ou um evento da Agenda.

Consulte o guia de estilo de complementos do Google Workspace para conferir 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 amplia.

Confira mais detalhes em Manifestos para o complemento do Google Workspace.

À 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.

Configurar a aparência e o comportamento do app Google Chat

Prévia para desenvolvedores:disponível como parte do Programa de prévia para desenvolvedores do Google Workspace, que concede acesso antecipado a determinados recursos.

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 de chat. Para saber como fazer isso, consulte Configurar um app do Google Chat.

Criar 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 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 acionamento 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.

Observação: a falha na chamada de build() após o uso de classes de builder no serviço de cartão resulta em erros de tipo. As funções de acionamento, por exemplo, precisam retornar objetos Card. O retorno de objetos CardBuilder resulta em um erro.

Você pode usar outros serviços integrados do Apps Script, como o CalendarApp, para recuperar informações a serem exibidas nos cards de complemento 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 e que exigem o OAuth, será necessário configurar e se conectar a esse serviço. Consulte o guia de conexão 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, você precisa usar esta ordem de construção:

1. Crie o widget.
2. Adicione o widget à seção do card.
3. Repita até que a seção do card tenha todos os widgets.
4. 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 de widget depois de adicioná-lo não são refletidas no card final.

Aviso: só adicione um widget a um card ou uma seção de card depois de concluí-lo. Só adicione uma seção de card a um card depois que ele for totalmente preenchido com os widgets. Não mude os widgets ou as seções depois de adicionar. Se você quiser fazer uma mudança em um widget adicionado, recrie a seção ou o card em que ele foi adicionado.

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 exibido. Todas as ações universais definidas aparecem sempre no menu do 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 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 manifest 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.

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

• Testar e depurar complementos do Google Workspace para o Apps Script
• Testar e depurar complementos HTTP do Google Workspace
• Testar recursos interativos dos apps do Google Chat

Publicar o complemento

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

Consulte Publicar um complemento do Google Workspace para mais detalhes.