# Conectar a Cloudflare

> Como conectar a Cloudflare ao Agent Analytics com um token de leitura e, se quiser ir além, instalar o Worker da Bases para ver também as pessoas vindas de IA.

Se o seu site passa pela Cloudflare, a Bases lê dela as visitas dos robôs de IA. Há dois níveis:

1. **Token de leitura:** a Bases consulta as visitas de robôs de hora em hora. Leva cinco minutos e funciona no plano gratuito da Cloudflare.
2. **Worker da Bases:** um script que você instala na Cloudflare. Ele confere o endereço IP de cada robô e mostra também as pessoas que chegam vindas de uma IA.

Comece pelo token. O Worker é um passo a mais, para quem quer as visitas de pessoas sem depender do Google Analytics.

> **Nota:** só o proprietário e os administradores da conta conectam fontes. O site precisa estar com o proxy da Cloudflare ligado, a nuvem laranja.

## Conectar com o token

### 1. Criar o token

1. Na Bases, vá a **Agent Analytics › Configurações**. Em **Fontes de dados**, clique em **Conectar fonte**.
2. Clique em **Criar o token na Cloudflare**. A Cloudflare abre o formulário já preenchido: o nome "Bases (leitura)", a leitura de Analytics e de zona, e todos os sites da conta.
3. Se quiser limitar o token a um site, troque **All zones** pelo seu site, em **Zone Resources**.
4. Clique em **Continue to summary** e depois em **Create Token**.
5. Copie o token. A Cloudflare mostra ele uma vez só.

O token só permite ler. Com ele, a Bases não muda nada na sua conta da Cloudflare.

### 2. Conectar na Bases

1. De volta à Bases, cole o token no campo e clique em **Conectar**.
2. A Bases acha o site na Cloudflare pelo domínio cadastrado e já testa a leitura. Se der certo, aparece "Conectado".

O campo **Zone ID** é opcional. Ele só é preciso quando o domínio cadastrado na Bases não é o mesmo da Cloudflare. O Zone ID fica na página inicial do site na Cloudflare (Overview), na coluna da direita.

A linha da Cloudflare passa a mostrar "Conectado", com o começo do Zone ID e o final do token. Os botões **Trocar**, **Testar** e **Remover** ficam na mesma linha.

### Se não conectar

| Mensagem | O que fazer |
|---|---|
| A Cloudflare não reconheceu este token. | O valor colado não é o token. Crie outro e copie o token inteiro, logo depois de **Create Token**. |
| O token vale, mas não tem permissão para ler as estatísticas deste site. | Crie um token novo pelo botão **Criar o token na Cloudflare**, que já marca as permissões. |
| O token não enxerga o site na Cloudflare. | No token, deixe **All zones** ou escolha este site. Ou informe o Zone ID. |
| Cadastre o site da marca. | Preencha o site em **AI Insights › Configurações › Detalhes da marca**, ou informe o Zone ID. |

Para trocar um token que falhou, clique em **Trocar** na linha da Cloudflare.

### Quando aparecem os dados

A Bases lê a Cloudflare de hora em hora. A primeira leitura traz cerca dos últimos 7 dias, porque o plano gratuito da Cloudflare guarda 8 dias de histórico.

O token não traz as pessoas vindas de IA: a Cloudflare não informa de onde cada visita veio. Para isso, instale o Worker ou conecte o [Google Analytics](/agent-analytics/google-analytics/).

## Instalar o Worker

O Worker roda na própria Cloudflare, a cada visita ao site. Primeiro ele entrega a página e só depois manda o registro da visita para a Bases. Se a Bases não responder, o site não percebe.

> **Importante:** mantenha o token de leitura conectado mesmo depois de instalar o Worker. Com o Worker funcionando, a Bases para de consultar a Cloudflare e passa a usar o que o Worker manda.

### Instalação automática

A Bases instala o Worker por você, usando um token de instalação que só vale para isso.

1. Em **Agent Analytics › Configurações**, na seção **Worker da Cloudflare**, clique em **Criar o token de instalação na Cloudflare**. A Cloudflare abre o formulário já preenchido, com as permissões de publicar Workers e de ligar rotas.
2. Clique em **Continue to summary** e depois em **Create Token**. Copie o token.
3. Volte, cole o token e clique em **Instalar o Worker**.

A Bases faz, na sua conta da Cloudflare:

- publica o Worker "bases-agent-analytics", com o token de ingestão guardado como segredo;
- liga as rotas do site, com e sem www, com o modo **Fail open**;
- deixa de fora as pastas de imagens, CSS e JavaScript que ela acha na página inicial;
- se o site já tem outro Worker, coloca esse atrás do da Bases, e os dois continuam funcionando.

A Bases usa o token de instalação só nessa hora e não o guarda. Depois, você pode apagá-lo na Cloudflare, em **My Profile › API Tokens**.

A instalação gera um token de ingestão novo, e o anterior deixa de valer. Se o site tiver mais de um Worker atendendo todas as páginas, a instalação automática não mexe em nada e pede a instalação à mão.

### Instalação à mão

Para instalar pelo painel da Cloudflare, sem dar à Bases permissão de escrita:

1. Em **Agent Analytics › Configurações**, na seção **Token de ingestão**, clique em **Gerar token** e depois em **Copiar token**. Ele aparece uma vez só. **Gerar novo token** invalida o anterior na hora, inclusive no Worker já instalado.
2. Clique em **Baixar worker-bases.js**.
3. Na Cloudflare, vá a **Workers & Pages**, clique em **Create** e escolha **Worker**. Cole o conteúdo do arquivo e publique com **Deploy**.
4. No Worker, vá a **Settings › Variables and Secrets** e crie a variável **BASES_TOKEN**, do tipo **Secret**, com o token copiado.
5. Em **Workers Routes**, crie a rota `seusite.com.br/*` apontando para o Worker, com o modo de falha **Fail open**. Se o site também abre com www, crie a rota `www.seusite.com.br/*`.
6. Crie rotas com o Worker **None** para as pastas de arquivos:
   - WordPress: `/wp-content/*` e `/wp-includes/*`;
   - Next.js: `/_next/*`;
   - outros sites: a pasta das imagens e do CSS, como `/assets/*`, `/static/*` ou `/images/*`.

> **Atenção:** crie o BASES_TOKEN como **Secret**. Como variável comum, o token fica visível em texto aberto no painel.

**Se já existe outro Worker na rota:** a Cloudflare roda um Worker só por visita. Deixe a rota com o Worker da Bases e ligue o outro atrás dele. No Worker da Bases, vá a **Settings › Bindings**, crie um **Service binding** (no painel em português, "Associação de serviço") para o outro Worker e dê a ele o nome `WORKER_SEGUINTE`.

### Conferir

Em **Agent Analytics › Configurações**, a linha **Worker da Cloudflare** passa a mostrar "Recebendo" e há quanto tempo chegou o último envio. As visitas contam a partir da instalação, sem histórico anterior.

## O que o Worker envia

- **Robôs:** o horário, o endereço da página, o código de resposta, o robô (user agent) e o endereço IP, para a Bases conferir se o robô é quem diz ser.
- **Pessoas:** só a entrada no site vinda de outro endereço, com a página e a origem. Sem IP, sem identificação do navegador e sem cookies.

O Worker nunca lê o conteúdo das páginas e não envia nada de endereços como carrinho, checkout, área do cliente, `/admin`, `/wp-admin` e `/api`.

## Limites do plano gratuito da Cloudflare

O plano gratuito de Workers aceita 100 mil visitas por dia. Acima disso, o site segue no ar, mas o resto do dia não é contado. A aba **Visitas** avisa quando um dia pode ter ficado incompleto.

## Desconectar

- **Token:** em **Agent Analytics › Configurações**, clique em **Remover**. O histórico já lido continua guardado.
- **Worker:** apague a rota na Cloudflare. Para cortar o envio na hora, gere um token novo na Bases.

## Próximos passos

- [Conectar o Google Analytics](/agent-analytics/google-analytics/)
- [Perguntas frequentes](/agent-analytics/perguntas-frequentes/)