Instalar e autorizar complementos

Os usuários precisam instalar e autorizar um complemento antes de abrir e usar. Como essas etapas são a primeira parte da experiência do usuário do complemento, é importante entendê-las 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 complementos.

Instalar complementos

Antes de usar um complemento, é preciso 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 no 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, é preciso autorizá-lo.

Para mais detalhes, consulte Publicar complementos.

Autorizar complementos

Depois de instalado, o complemento 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 um cartão ou caixa de diálogo de autorização. Esse card explica o que o complemento precisa de permissão para fazer pelo usuário, como acessar o conteúdo da planilha Google atual. O usuário pode conceder essas permissões e permitir que o complemento continue. Se o usuário negar a autorização do complemento, ele não poderá usá-lo.

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 ver a lista de autorizações que o complemento precisa para funcionar, assim você sabe o que ele tenta fazer. Analise essa lista com cuidado e, se 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 para que o complemento fique disponível.

Se o complemento instalado for atualizado e exigir outras autorizações que você ainda não concedeu, será solicitado que você forneça essas permissões na próxima vez que usar o complemento.

Autorizar complementos não publicados do Google Workspace

Cartão de autorização complementar

Os complementos não publicados não têm o mesmo fluxo de autorização dos complementos publicados porque ainda não estão listados no Google Workspace Marketplace. Depois de instalar um complemento não publicado, você não precisa autorizar 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 a autorização for necessária, o complemento vai apresentar um cartão de autorização. A autorização é sempre necessária na primeira vez que um complemento é executado e também pode ser necessária se uma nova versão do complemento usar um serviço que não foi autorizado antes. O botão Autorizar acesso abre uma caixa de diálogo para o usuário permitir ou negar a autorização do complemento.

Autorizar serviços que não são do Google para um complemento do Google Workspace

É possível que um complemento do Google Workspace se conecte a um serviço de terceiros que também exige 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 é do Google usando o OAuth, configure 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 videoconferê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 aos usuários selecionar um sistema de videoconferência de terceiros ao editar eventos do Google Agenda. Se o complemento oferecer opções de conferência que exijam que o usuário faça login, ele precisa permitir que o usuário faça isso.

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

Ao receber esse objeto, o Google Agenda cria um botão FAZER LOGIN na interface de edição de eventos que se vincula ao URL de autenticação fornecido pelo complemento. Em seguida, os usuários podem usar esse botão para fazer login no sistema terceirizado antes de usar o complemento.

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

Autorizar complementos do Editor não publicados

É uma prática recomendada testar os complementos do Editor à medida que você os desenvolve. O fluxo de autorização é idêntico ao dos complementos do Editor publicados, exceto que ele começa quando você tenta testar o complemento pela primeira vez. Se você testar novamente o mesmo complemento, não vai precisar dar autorização de novo.

Remover a autorização de complementos

Ao desenvolver complementos, pode ser útil cancelar a autorização deles para testar novamente o fluxo de autorização.

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

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

Quando você executa o complemento novamente depois de revogar a autorização, o fluxo de autorização é apresentado de novo.

Desinstalar complementos

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

Para desinstalar um complemento não publicado criado no Apps Script, consulte Desinstalar um complemento não publicado.