Documentation | No Boss Extensions

Guia de Configuração: API do Google Calendar para NoBossCalendar

Detalhes
Escrito por Johnny Salazar Reidel
Categoria: No Boss Calendar

Este guia irá orientá-lo, passo a passo, no processo de criação das suas credenciais da API do Google Calendar. O objetivo é gerar as "chaves" necessárias para conectar o No Boss Calendar à sua conta Google de forma segura.

Pré-requisito: Ter uma conta Google (pode ser uma conta gratuita @gmail.com ou uma conta de trabalho do Google Workspace).

 

Vídeo Tutorial

Todos os passos descritos neste guia são também demonstrados visualmente no video abaixo.

 

Passo 1: Criar um Projeto no Google Cloud

Toda configuração de APIs no Google precisa ser organizada dentro de um "projeto".

  1. Acesse a página de seleção de projetos do Google Cloud clicando aqui.

  2. Na janela que aparecer, procure e clique no botão "Criar projeto" no canto superior direito.

  3. No campo Nome do projeto, digite No Boss Calendar.

  4. Clique no botão "CRIAR".

  5. Após a criação do projeto, você pode fechar esta aba do navegador para seguir para o próximo passo.

Passo 2: Ativar a API do Google Calendar

Com o projeto criado, precisamos "ligar" a API do Google Calendar para permitir que programas externos se comuniquem com ela.

  1. Antes de prosseguir, confirme se o projeto correto está selecionado. No topo da página, ao lado do logo "Google Cloud", deve estar escrito "No Boss Calendar".

  2. Acesse a Biblioteca de APIs do Google clicando aqui. Faça o login com sua conta Google, se solicitado.

  3. Na página que abrir, procure por um botão azul escrito "Ativar". Clique nele.

  4. Se o botão estiver escrito "Gerenciar", significa que a API já está ativa e você não precisa fazer nada.

  5. Após ativar, você pode fechar esta aba do navegador.

Passo 3: Configurar a Autenticação OAuth

Esta é a etapa inicial e fundamental da autenticação.

  1. Acesse a página de Visão Geral do OAuth clicando aqui.

  2. Você verá uma tela com o título "A plataforma de autenticação do Google ainda não foi configurada". Clique no botão azul "Vamos começar".

  3. A tela de "Configuração do projeto" aparecerá. Siga o preenchimento das 4 etapas:

    Etapa 1: Informações do app

    • Nome do app: Digite No Boss Calendar.

    • E-mail para suporte do usuário: Selecione o seu melhor e-mail para contato na lista.

    • Clique em "Avançar".

    Etapa 2: Público-alvo

    • Escolha a opção "Externo" (disponível para qualquer usuário com uma Conta do Google).

    • Clique em "Avançar".

    Etapa 3: Dados de contato

    • No campo Informações de contato do desenvolvedor, adicione seu e-mail de contato.

    • Clique em "Avançar".

    Etapa 4: Concluir

    • Marque a caixa de seleção que indica que concorda com a política de dados do Google.

    • Revise as informações e clique em "Continuar".

  4. Após concluir as 4 etapas, clique no botão "Criar". Você será levado de volta ao painel principal do OAuth.

Passo 4: Adicionar Usuários de Teste

Como seu aplicativo está em "Modo de Teste", você precisa informar ao Google quais contas de e-mail estão autorizadas a testar a integração. Sem este passo, o Google bloqueará qualquer tentativa de login.

  1. Acesse a página de Público-alvo clicando aqui.

  2. Na seção "Usuários de teste", clique no botão "+ ADICIONAR USUÁRIOS".

  3. Na janela que abrir, adicione o endereço de e-mail da conta Google que você usará para se conectar. Você pode adicionar múltiplas contas, se necessário.

  4. Clique em "SALVAR".

Passo 5: Criar as Credenciais de Acesso (ID de Cliente OAuth)

Nesta etapa, vamos criar as 'chaves' (ID do cliente e Chave secreta) e, para isso, precisaremos de uma URL específica que está dentro da extensão No Boss Calendar. Siga os passos com atenção.

  1. Acesse a página de Credenciais do Google Cloud clicando aqui.

  2. No topo da página, clique no botão "+ CRIAR CREDENCIAIS" e escolha a opção "ID do cliente OAuth".

  3. No campo "Tipo de aplicativo", selecione a opção "Aplicativo da Web".

  4. No campo "Nome", preencha No Boss Calendar.

  5. Na seção "Origens JavaScript autorizadas", clique em "+ ADICIONAR URI". Informe o domínio do seu site. Exemplo: https://www.seusite.com.br

  6. Agora, para o próximo campo, precisamos pegar uma URI de redirecionamento dentro da extensão No Boss Calendar instalada no seu site. Em outra aba do navegador:

    1. Acesse a área de administração do seu site.

    2. No menu, acesse o componente “No Boss Calendar” e depois o submenu “Calendários”.

    3. Na lista, clique sobre o nome do calendário que você deseja integrar.

    4. Na tela de edição do calendário, clique na aba “Integração Google Calendar”.

    5. Clique no botão “Configurar integração”.

    6. Uma janela (modal) irá aparecer (veja imagem abaixo). Copie a URL que é exibida no campo "URIs de redirecionamento". Mantenha esta janela aberta, pois voltaremos nela no Passo 6.

  7. De volta à página do Google Cloud, na seção "URIs de redirecionamento autorizados", clique em "+ ADICIONAR URI" e cole a URL que você acabou de copiar da modal. O URL completo será parecido com este exemplo: http://seusite.com.br/libraries/noboss/src/Form/Field/Nbapiconnection/NbCallbackProxy.php

Nota: de um site para outro muda apenas a url parte inicial da URI. O conteúdo da url a partir de "/administrator...." é igual para todos os sites que deseja informar como URL autorizada na conta do Google.

💡 Dica para Desenvolvedores: Se você estiver configurando um ambiente de teste na sua máquina local (localhost), adicione também os seguintes endereços:

  • Em "Origens JavaScript autorizadas", adicione http://localhost e também a versão com a porta que você usa, por exemplo: http://localhost:3000 ou http://localhost:8080.

  • Em "URIs de redirecionamento autorizados", adicione a mesma URL de redirecionamento do seu produto, mas trocando o domínio do site por localhost (ou localhost:porta). Exemplo: http://localhost/MY-WEBSITE/libraries/noboss/src/Form/Field/Nbapiconnection/NbCallbackProxy.php

  1. Após preencher os campos, clique em "CRIAR" no final da página.

⚠️ ATENÇÃO: PASSO MUITO IMPORTANTE!

Uma janela aparecerá com as suas credenciais.

  • Copie o valor do "ID do cliente"

  • Copie o valor da "Chave secreta do cliente"

Guarde estes dois valores num local seguro, como um bloco de notas. A Chave Secreta não será mostrada novamente! Trate-a como uma senha.

Passo 6: Configurar o Acesso aos Dados (Escopos)

Agora, na página "Acesso a dados", vamos dizer ao Google quais permissões exatas o No Boss Calendar pode solicitar. Faremos isto para garantir que ele só possa ler os eventos, mantendo tudo seguro.

  1. Acesse a página de Acesso a Dados clicando aqui.

  2. Na página que abrir, clique diretamente no botão "Adicionar ou remover escopos".

  3. Uma janela lateral irá abrir. Siga os passos abaixo para adicionar as permissões corretas:

    • No campo de pesquisa no topo, digite calendar.readonly e pressione Enter. Marque a caixa de seleção que aparecer, correspondente a .../auth/calendar.readonly.

    • Apague a pesquisa anterior. Agora, pesquise por events.readonly e pressione Enter. Marque a caixa de seleção que aparecer, correspondente a .../auth/calendar.events.readonly.

  4. Após marcar as duas opções, role para baixo na janela lateral e clique no botão "ATUALIZAR".

  5. De volta à página principal, clique no botão "SALVAR" no final da tela para confirmar as alterações.

Passo 7: Conectar a Extensão No Boss Calendar

Com as chaves de acesso em mãos, volte para a janela de integração (modal) que você abriu no Passo 4 dentro do seu site e siga os passos finais:

  1. Cole o “ID do cliente” e a “Chave secreta do cliente” que você copiou nos campos correspondentes.

  2. Clique no botão “Conectar com a API”.

  3. Uma nova aba do navegador será aberta, solicitando o login na sua conta Google e a permissão de acesso. Prossiga até finalizar a autenticação.

  4. Após a autenticação, a aba do Google será fechada automaticamente. Na janela de integração, o campo “Status” mudará para “Conectado”, com um fundo verde.

  5. Com a conexão ativa, as agendas da sua conta Google serão listadas logo abaixo do botão que você clicou para conectar com a API. Selecione quais agendas você deseja importar os eventos.

  6. Explore as outras abas, como “Dados dos eventos” e “Importação dos eventos”, para configurar regras adicionais, se desejar.

⚠️ ATENÇÃO: NÃO SE ESQUEÇA DE SALVAR!

Para que a integração fique salva e ativa, você precisa seguir estes dois últimos passos:

  1. Na janela de integração da área admin do seu site, clique no botão “Concluído” para fechar a modal.

  2. De volta à tela de edição do calendário, clique no botão principal “Salvar” (ou “Salvar e Fechar”).

Se estes dois passos não forem feitos, toda a configuração da conexão será perdida.

Entendendo o "Modo de Teste" e Próximos Passos

Parabéns! Suas credenciais estão prontas e a integração já está funcional.

Por padrão, seu aplicativo no Google Cloud começa no "Modo de Teste". É importante que você entenda as limitações deste modo:

Apenas Usuários de Teste Podem se Conectar

Enquanto o aplicativo estiver em teste, o Google bloqueará qualquer tentativa de login de contas que não foram explicitamente adicionadas na lista de "Usuários de teste" (conforme o Passo 4). Isso significa que apenas as contas de e-mail que você cadastrou poderão autorizar a integração.

A Tela de "App não verificado"

Ao conectar sua conta Google (sendo ela um usuário de teste), o Google exibirá uma tela de aviso com o título "Este app não foi verificado".

  • Não se preocupe, isto é normal! A mensagem aparece porque o aplicativo ainda não passou pelo processo de verificação formal do Google.

  • Para prosseguir, clique em "Avançado" e, em seguida, no link que diz "Acessar No Boss Calendar (não seguro)". Isto permitirá que a conexão seja feita.

A Validade da Conexão (Expira em 7 dias)

A outra principal limitação do "Modo de Teste" é que a autorização que você acabou de dar expira a cada 7 dias.

  • O que acontece na prática? Após 7 dias, a extensão não conseguirá mais se comunicar com a API do Google. Com isso, ela deixará de buscar e exibir automaticamente os novos eventos do seu calendário no site.

  • Como resolver? É simples. A cada 7 dias, você precisará acessar a área de administração da sua extensão no site e se autenticar novamente com a conta do Google, reativando a permissão por mais uma semana.

Solução Definitiva: Publicar o Aplicativo

Manter o aplicativo em "Modo de Teste" é uma opção totalmente viável se você não se importar em lidar com as limitações acima.

Para removê-las e tornar a conexão permanente, a solução é solicitar a verificação do aplicativo ao Google, mudando o status para "Em produção". Este é um processo mais formal, que exige o envio de informações detalhadas ao Google sobre como a sua integração utiliza os dados do calendário. Uma equipe do Google irá avaliar sua solicitação para garantir que tudo está de acordo com as políticas de privacidade e segurança antes de aprovar.

Categorias