Instalar e autorizar complementos

Os usuários precisam instalar e autorizar um complemento antes de abri-lo e usá-lo. Como essas etapas são a primeira parte da experiência do usuário do complemento, você precisa entendê-las antes de começar a criar seus próprios complementos.

Esta seção de 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 do 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, é necessário autorizá-lo.

Para mais detalhes, consulte Publicar complementos.

Autorizar complementos

Depois de instalar um complemento, ele fica disponível no aplicativo host do Google Workspace que estende. Na primeira vez que um usuário tenta usar o complemento, o aplicativo host mostra um cartão de autorização ou uma caixa de diálogo. Este card explica o que o complemento precisa de permissão para fazer para o usuário, por exemplo, 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á usar o complemento.

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

Autorizar complementos publicados

Depois que você instala um complemento publicado, o fluxo de autorização começa imediatamente:

  1. Será preciso Escolher uma conta para instalar o complemento.
  2. Em seguida, você verá a lista de autorizações que o complemento exige para operar, para que saiba o que ele tenta fazer. Analise essa lista com atenção e, se ainda quiser conceder autorização, clique em Permitir. Isso ativa o uso do complemento.
  3. Agora você pode executá-lo a partir do aplicativo host que ele estende. Se o aplicativo já estava 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 posteriormente e exigir outras autorizações que você ainda não concedeu, será necessário fornecer essas permissões na próxima vez que 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 que os já publicados porque ainda não estão listados no Google Workspace Marketplace. Depois de instalar um complemento não publicado, você não receberá imediatamente uma solicitação de autorização. Em vez disso, o fluxo de autorização é iniciado quando você tenta usar o complemento pela primeira vez.

Quando um complemento é executado, ele determina se alguma autorização do usuário é necessária. Se uma autorização for necessária, o complemento apresentará um cartão de autorização. A autorização é sempre exigida 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 não autorizado anteriormente. O botão Autorizar acesso abre uma janela de diálogo para permitir ou negar a autorização do 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 requer 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 complemento quando ele é instalado ou iniciado pela primeira vez
  • Autorização do serviço que não é do Google quando é 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 desse 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 aos usuários selecionar um sistema de videoconferência de terceiros ao editar eventos do Google Agenda. Se seu complemento tiver opções de videoconferência que exigem que o usuário faça login, ele precisa permitir que o usuário faça isso.

Se um usuário tentar criar uma videoconferência com seu complemento sem o login necessário, o método onCreateFunction das soluções de conferência retornará um objeto ConferenceData contendo 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 do evento que o vincula ao 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 Como criar videoconferê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 durante o desenvolvimento deles. O fluxo de autorização é idêntico ao dos Complementos do Editor publicados, exceto que o fluxo é iniciado quando você tenta testar o complemento pela primeira vez. Se você testar novamente o mesmo complemento, não receberá outra solicitação de autorização.

Cancelar autorização de complementos

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

Para desautorizar 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 desautorizá-lo, o fluxo de autorização é apresentado novamente.