Instalar e autorizar complementos

Os usuários precisam instalar e autorizar um complemento antes de abrir e usá-lo. Como essas etapas são a primeira parte da experiência do usuário com o complemento, é importante que você as entenda antes de começar a criar seus próprios complementos.

Esta seção da documentação descreve como os usuários podem instalar, autorizar e começar a usar os complementos.

Instalar complementos

Antes de usar um complemento, é necessário instalá-lo. Depois de instalado, o complemento fica disponível no aplicativo host do Google Workspace que ele estende.

É possível instalar complementos publicados no aplicativo host do Google Workspace ou no Google Workspace Marketplace. Os administradores de domínio também podem instalar complementos em nome dos usuários pelo Google Workspace Marketplace. Também é possível instalar complementos não publicados que você está desenvolvendo para testá-los. Antes de usar um complemento instalado pela primeira vez, é necessário autorizar ele.

Para mais detalhes, consulte Publicar complementos.

Autorizar complementos

Depois de instalar um complemento, ele fica disponível no aplicativo host do Google Workspace que ele estende. Na primeira vez que um usuário tenta usar o complemento, o aplicativo host apresenta a ele uma caixa de diálogo ou um card de autorização. Esse card explica o que o complemento precisa fazer para o usuário, como acessar o conteúdo da planilha atual. O usuário pode conceder essas permissões e permitir que o complemento continue. Se o usuário negar a autorização, ele não poderá usar o complemento.

Os complementos do editor usam um modelo de autorização diferente dos complementos do Google Workspace. Como os complementos do Editor funcionam em arquivos do Google Drive, o modelo de autorização do editor define vários modos de autorização que resultam quando os complementos são usados com arquivos individuais. Ao desenvolver complementos do editor, é importante entender os diferentes modos e como um complemento se move entre eles.

Autorizar complementos publicados

Depois de instalar um complemento publicado, o fluxo de autorização começa imediatamente:

  1. Você vai precisar escolher uma conta para instalar o complemento.
  2. Em seguida, você vai receber a lista de autorizações que o complemento precisa para funcionar, para que você saiba o que ele tenta fazer. Analise essa lista com cuidado e, se você ainda quiser conceder a autorização, clique em Permitir. Isso ativa o complemento para uso.
  3. Agora, é possível executá-lo no aplicativo host que ele estende. Se o aplicativo já estiver aberto em uma guia do navegador, talvez seja necessário atualizar a guia antes que o complemento fique disponível.

Se o complemento instalado for atualizado mais tarde e exigir autorizações adicionais que você ainda não concedeu, será necessário fornecer essas permissões na próxima vez que você usar o complemento.

Autorizar complementos não publicados do Google Workspace

Cartão de autorização de complemento

Os complementos não publicados não têm o mesmo fluxo de autorização dos publicados porque ainda não estão listados no Google Workspace Marketplace. Depois de instalar um complemento não publicado, você não precisa dar autorização imediatamente. Em vez disso, o fluxo de autorização começa quando você tenta usar o complemento pela primeira vez.

Quando um complemento é executado, ele determina se é necessária alguma autorização do usuário. Se for necessário, o complemento vai apresentar um cartão de autorização. A autorização é sempre necessária na primeira execução de um complemento e também pode ser necessária se uma nova versão do complemento usar um serviço não autorizado anteriormente. O botão Authorize Access (autorizar acesso) oferece uma janela de diálogo para que o usuário permita ou negue a autorização para o complemento.

Autorizar serviços de terceiros para um complemento do Google Workspace

É possível que um complemento do Google Workspace se conecte a um serviço de terceiros que exija autorização. Os complementos do Google Workspace que se conectam a esses serviços exigem duas ações separadas do usuário:

  • Autorização do próprio complemento quando ele é instalado ou iniciado pela primeira vez.
  • Autorização do serviço que não é do Google quando ele é acessado pela primeira vez.

Se um complemento do Google Workspace que você está desenvolvendo precisar acessar um serviço que não seja do Google usando o OAuth, será necessário configurar a conexão para esse serviço ao criar o complemento.

Para mais informações, consulte Conectar o complemento do Google Workspace a um serviço de terceiros.

Sistemas de conferência de terceiros

Os complementos do Google Workspace que estendem o Google Agenda também podem adicionar outras soluções de videoconferência que permitem que os usuários selecionem um sistema de videoconferência de terceiros ao editar eventos do Google Agenda. Se o complemento oferece opções de conferência que exigem que o usuário faça login, ele precisa dar ao usuário a capacidade de fazer isso.

Se um usuário tentar criar uma conferência com seu complemento sem fazer o login necessário, o método onCreateFunction das soluções de conferência vai retornar um objeto ConferenceData contendo um ConferenceError com um URL de autenticação.

Ao receber esse objeto, o Google Agenda cria um botão LOG IN na interface de edição de eventos que vincula o URL de autenticação fornecido pelo complemento. Os usuários podem usar esse botão para fazer login no sistema de terceiros antes de usar o complemento.

Consulte Criar conferências de terceiros para mais detalhes sobre como processar a autorização usando ConferenceError.

Autorizar complementos não publicados do editor

É recomendável testar os complementos do Editor durante o desenvolvimento. O fluxo de autorização é idêntico ao dos complementos do Editor publicados, exceto que o fluxo começa quando você tenta testar o complemento pela primeira vez. Se você testar novamente o mesmo complemento, não vai ser necessário fazer a autorização de novo.

Cancelar a autorização de complementos

Ao desenvolver complementos, pode ser útil desautorizá-los para que você possa testar o fluxo de autorização novamente.

Para cancelar a autorização de um complemento, faça o seguinte:

  1. Abra o console de segurança da conta.
  2. Localize e clique no complemento que você quer desautorizar.
  3. Clique em Remover acesso.

Quando você executa o complemento novamente após desautorizar, o fluxo de autorização é apresentado novamente.

Desinstalar complementos

Para desinstalar um complemento instalado no Google Workspace Marketplace, consulte Desinstalar um app ou complemento do Marketplace.

Para desinstalar um complemento não publicado integrado ao Apps Script, consulte Desinstalar um complemento não publicado.