> For the complete documentation index, see [llms.txt](https://docs.airops.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.airops.com/docs/pt/insights/onsite/traffic/vercel-agent-analytics.md).

# Vercel

Conecte o seu projeto Vercel ao AirOps para monitorizar o tráfego de bots de IA através de Vercel Log Drains.

Conecte o seu projeto Vercel ao AirOps para monitorizar o tráfego de bots de IA. O AirOps provisiona automaticamente um **Vercel Log Drain** quando instala a integração, classifica visitas de bots de IA (ChatGPT, Claude, Perplexity, Google e mais) e apresenta insights no seu painel de Agent Analytics.

***

### Pré-requisitos

* Uma **AirOps** conta ativa com Agent Analytics ativado
* Uma **Vercel Pro ou Enterprise** conta (os Log Drains não estão disponíveis nos planos Hobby)
* Uma **projeto Vercel** a servir o seu site num domínio personalizado
* Uma **Brand Kit** no AirOps cujo domínio corresponda ao domínio de implementação da sua Vercel (configurável em Context > Brand Kits > Brand URL)

Se não tiver a certeza de que o seu brand kit está configurado corretamente, confirme com o seu contacto de Customer Success do AirOps antes de instalar.

***

### Passo 1: Instale o AirOps a partir do Vercel Marketplace

1. Abra o URL de instalação: [`https://vercel.com/integrations/airops-agent-analytics/new`](https://vercel.com/integrations/airops-agent-analytics/new)
2. A Vercel mostra um seletor de equipa. Selecione a **equipa Vercel** que é proprietária do projeto que pretende monitorizar.
3. A Vercel mostra o **Instalar o AirOps Agent Analytics** ecrã. Em "Select which projects the integration will have access to", escolha **Projetos Específicos** e selecione apenas o(s) projeto(s) que servem o site da sua marca monitorizado.
4. Clique em **Instalar**.

{% hint style="info" %}
Recomendamos vivamente **Projetos Específicos** em vez de **Todos os Projetos**. "Todos os Projetos" dá à integração acesso a todos os projetos da sua equipa Vercel, incluindo os não relacionados (sites de marketing, ferramentas internas, implementações de pré-visualização). O AirOps filtra os registos que não correspondem ao domínio do seu brand kit antes de os armazenar, mas ainda assim geram custos de saída do drain da Vercel (aproximadamente 0,50 US$ por GB) na sua fatura. Selecionar apenas o projeto do site da marca mantém os custos da Vercel previsíveis e evita transmitir tráfego que será descartado.
{% endhint %}

***

### Passo 2: Ligue ao seu Workspace do AirOps

Depois de autorizar na Vercel, será redirecionado de volta para o AirOps.

* Se a sua conta AirOps tiver acesso a **um workspace**, a integração liga-se automaticamente.
* Se tiver acesso a **vários workspaces**, aparece um seletor. Selecione o workspace ao qual pretende associar esta integração da Vercel.

O AirOps provisiona automaticamente um Vercel Log Drain na sua equipa selecionada. Não é necessária configuração manual de URLs de endpoint, segredos de assinatura ou cabeçalhos Bearer.

Será redirecionado para a página de integração AirOps Agent Analytics na Vercel, confirmando que a instalação está concluída.

***

### Passo 3: Verifique a ligação

No AirOps, navegue para **Insights > Settings > General** para qualquer brand kit e desloque-se até à **Integrações ligadas** secção.

Deverá ver uma **Vercel** linha com:

* Um **Conectado** selo verde
* O nome da sua equipa Vercel ligada
* Uma **Desinstalar na Vercel** ação

Os dados começam a fluir assim que o seu site recebe tráfego de um bot de IA. Em volumes de tráfego baixos, a Vercel agrupa os registos e entrega-os a cada **30 a 60 segundos**.

{% hint style="warning" %}
O botão **Testar** da Vercel (nas definições de Drains do lado da Vercel) envia apenas registos sintéticos sem dados de pedido. Um Teste bem-sucedido **não** significa que tráfego real aparecerá no AirOps; apenas confirma que o endpoint está acessível. O tráfego real de agentes chega assim que um bot de IA faz um pedido ao seu site que corresponda aos projetos configurados.
{% endhint %}

<figure><img src="https://31915162-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FX2n5yPRPynbnWuO4SH0M%2Fuploads%2Fgit-blob-af54a5d372532d53bdeaf65d70dc7566611d100d%2Fagent-vercel-01-setup-panel.png?alt=media" alt="Set up Agent Analytics source picker with Vercel marked Connected, next to CloudFront, Cloudflare Worker, and Netlify"><figcaption><p>A Vercel mostra-se como Conectado assim que a integração do AirOps é instalada.</p></figcaption></figure>

***

### Resolução de problemas

| Sintoma                                                                           | Causa provável                                                                                                    | Correção                                                                                                                                                                                                                    |
| --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A linha da Vercel mostra **Conectado** mas não aparecem dados em Insights Traffic | O domínio do seu brand kit não corresponde ao domínio de implementação da sua Vercel                              | No AirOps, abra as definições do Brand Kit e confirme que a Brand URL corresponde ao domínio que o seu projeto Vercel realmente serve (por exemplo, `acme.com` não `www.acme.com` se o seu site for servido em `acme.com`). |
| A Vercel envia-lhe "drain errored"                                                | O endpoint do AirOps devolveu 4xx/5xx em mais de 50 entregas numa hora, ou em mais de 80% das entregas numa hora  | Contacte o Customer Success do AirOps. Podemos diagnosticar a partir dos registos do servidor.                                                                                                                              |
| O drain aparece como "active" mas não surgem linhas após 5 minutos                | Testou com o URL de implementação gerado automaticamente pela Vercel (por exemplo, `<project>-<hash>.vercel.app`) | A Proteção de Implementação da Vercel nos planos Pro devolve 401 aos bots nestes URLs. Em vez disso, use o alias público do seu projeto ou um domínio personalizado.                                                        |
| O botão Teste passa, mas nunca aparecem dados reais                               | Acertou em caminhos que devolvem 404 numa implementação estática                                                  | Os 404 em implementações apenas estáticas são servidos a partir da cache de edge da Vercel sem invocar o drain. Visite um caminho conhecido e válido que realmente exista na sua implementação.                             |
| A coluna Bytes mostra 0 para alguns pedidos                                       | Os acessos estáticos em cache não incluem `responseByteSize`                                                      | Isto é esperado em ativos estáticos em cache da Vercel. Outras métricas (estado, user-agent, tempo) não são afetadas.                                                                                                       |
| Removeu a integração na Vercel, mas o AirOps ainda mostra **Conectado**           | A página está a mostrar um estado desatualizado                                                                   | Faça um hard refresh da página do AirOps (Cmd+Shift+R no Mac, Ctrl+Shift+R no Windows). O webhook de desinstalação da Vercel é assíncrono e demora alguns segundos a chegar.                                                |

***

### Requisitos de plano

Os Vercel Log Drains estão disponíveis apenas nos **planos Vercel Pro e Enterprise** . Os planos Hobby não podem criar drains; se a sua equipa estiver no Hobby, terá de fazer upgrade antes de instalar.

A Vercel cobra o egresso do drain a aproximadamente 0,50 US$ por GB transmitido, cobrado na sua fatura da Vercel. Para sites com pouco tráfego, isto é normalmente inferior a 1 US$ por mês. Para sites com muito tráfego, reduza o custo de duas formas: limite a instalação a **Projetos Específicos** apenas no projeto do site da marca (ver Passo 1) e, nas definições por ambiente da Vercel, comece apenas com Produção e exclua as implementações de pré-visualização.

***

### Configuração de segurança e de menor privilégio

#### Permissões necessárias para instalar

**Na Vercel:** qualquer utilizador com a **Membro** função na sua equipa Vercel pode instalar a integração. Não é necessário ser Owner. A configuração de integrações faz parte das responsabilidades padrão da função Member ([funções de acesso da Vercel](https://vercel.com/docs/rbac/access-roles)).

**No AirOps:** o utilizador que conclui a instalação deve ter sessão iniciada no AirOps e ser membro do workspace de destino, e qualquer função do AirOps serve.

#### Utilizador dedicado ao estilo de serviço

O AirOps não tem um primitivo separado de identidade de máquina distinto de um utilizador, mas a integração foi concebida para que o utilizador que instala seja apenas o ator da instalação e não o principal em tempo de execução. Pode satisfazer as expectativas de menor privilégio tratando uma conta de utilizador dedicada como um proxy de conta de serviço:

1. Convide um utilizador nomeado e dedicado (por exemplo, `vercel-airops@yourcompany.com`) para o seu workspace do AirOps. Use a função de menor privilégio que o seu workspace oferecer.
2. Inicie sessão como esse utilizador uma vez e conclua a instalação OAuth.
3. Após a instalação estar concluída, esse utilizador não tem autoridade em tempo de execução. A integração continua a autenticar-se através do token API do workspace descrito abaixo. Pode remover o utilizador do workspace depois, se a sua política de segurança o exigir; a integração continua a funcionar.

O mesmo padrão aplica-se do lado da Vercel: um utilizador Vercel dedicado com a função Member pode fazer a instalação e depois permanecer como um membro inativo da equipa.

#### Autenticação em tempo de execução

Após a instalação, nenhuma sessão de utilizador está envolvida em qualquer entrega do drain. A autenticação em cada entrega tem duas camadas:

* **assinatura HMAC-SHA1** do corpo do pedido, assinado com um segredo de drain por instalação gerado pelo AirOps no momento da instalação. A Vercel envia a assinatura no `x-vercel-signature` cabeçalho em cada entrega.
* **Token Bearer** no `Authorization` cabeçalho. O token é a **chave de API do AirOps do workspace**, escrita na configuração do drain durante a instalação.

Ambos os fatores estão ao nível do workspace, não ao nível do utilizador. O utilizador que instala é registado apenas nos metadados de auditoria do AirOps.

#### Rotação de tokens

A chave API do workspace pode ser rodada na aplicação em **Account > Workspace > API Key** (requer a função de administrador do workspace do AirOps). Há duas coisas a entender antes de rodar:

* O drain da Vercel tem o token anterior incorporado no seu `Authorization` cabeçalho de saída. Após a rotação, o drain começará a falhar na autenticação até que a integração seja reinstalada a partir da Vercel (o que escreve o novo token num novo drain).
* A mesma chave API do workspace autentica outras APIs do AirOps (API Pública, servidor MCP, SDK). Rotacioná-la afeta todas elas, não apenas a Vercel.

Se a cadência de rotação fizer parte da sua política de conformidade, a sequência segura é: rode o token do AirOps e, em seguida, reinstale imediatamente a integração da Vercel a partir da listagem do marketplace da Vercel.

#### O que esta integração não faz

* Não solicita permissões na sua conta Vercel além do que é necessário para criar e gerir um log drain na equipa selecionada. Não pode ler o código-fonte do projeto, variáveis de ambiente ou registos de implementação fora do fluxo de pedidos do drain.
* Não escreve de volta na sua conta Vercel de forma contínua. Após o provisionamento inicial do drain, o AirOps apenas recebe dados da Vercel; não volta a chamar a API da Vercel a menos que reinstale ou desligue.

Se a sua revisão de segurança precisar de detalhes adicionais, contacte o Customer Success do AirOps e podemos acompanhar a sua equipa através do fluxo de dados ao nível da implementação.

***

### Desligar

Para remover a integração da Vercel:

1. No AirOps, abra **Insights > Settings > General > Connected Integrations**.
2. Clique em **Desinstalar na Vercel** na linha da Vercel. Isto leva-o à página de integrações da sua equipa Vercel.
3. Encontre a integração AirOps e clique em **Remover**. Confirme.
4. O AirOps marca a integração como **Desconectado** na sua próxima atualização de página.

Os seus dados históricos da Vercel permanecem no AirOps após a desconexão. Para retomar o acompanhamento, clique em **Reinstalar na Vercel** na mesma linha.

***

### O que o AirOps monitoriza

Depois de ligado, o AirOps automaticamente:

* **Ingere todos os pedidos servidos pela Vercel:** visualizações de página, ativos, chamadas de API
* **Classifica o tráfego de bots de IA:** identifica visitas do ChatGPT, Claude, Google, Perplexity, Meta, Apple, Bing, Bytedance, Common Crawl e outros
* **Categoriza o comportamento de rastreio:** distingue entre rastreadores de treino de IA (GPTBot, ClaudeBot, etc.), pedidos de pesquisa de IA (PerplexityBot, OAI-SearchBot, etc.) e navegação de IA iniciada pelo utilizador (ChatGPT-User, Claude-User, etc.)
* **Apresenta análises:** desdobramentos de tráfego, rácios bot vs. humano e tendências de rastreio no seu painel


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.airops.com/docs/pt/insights/onsite/traffic/vercel-agent-analytics.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
