> 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. Associe o seu projeto Vercel ao AirOps para acompanhar o tráfego de bots de IA. O AirOps aprovisiona 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 Agent Analytics. *** ### Pré-requisitos * Uma **AirOps** conta ativa com o 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: Instalar 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 acompanhar. 3. A Vercel apresenta o ecrã **Instalar AirOps Agent Analytics** . Em "Select which projects the integration will have access to", escolha **Specific Projects** e escolha apenas o(s) projeto(s) que servem o site da sua marca monitorizada. 4. Clique em **Instalar**. {% hint style="info" %} Recomendamos fortemente **Specific Projects** em vez de **All Projects**. "All Projects" 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 estes ainda geram custos de saída do drain da Vercel (aproximadamente 0,50 $/GB) na sua fatura. Escolher 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: Ligar ao seu Espaço de Trabalho AirOps Depois de autorizar na Vercel, será redirecionado de volta para o AirOps. * Se a sua conta AirOps tiver acesso a **um espaço de trabalho**, a integração liga-se automaticamente. * Se tiver acesso a **vários espaços de trabalho**, aparece um seletor. Selecione o espaço de trabalho ao qual pretende associar esta integração da Vercel. O AirOps aprovisiona automaticamente um Vercel Log Drain na 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: Verificar 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: * Uma **Connected** verde * insígnia * Uma **O nome da sua equipa Vercel ligada** Desinstalar na Vercel 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 agrega os registos e entrega-os a cada **30 a 60 segundos**. {% hint style="warning" %} O **botão Test** (nas definições de Drains do lado da Vercel) envia apenas registos sintéticos sem dados de pedido. Um Test bem-sucedido **não** significa que o 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 %} *** ### Resolução de problemas | Sintoma | Causa provável | Correção | | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | A linha da Vercel mostra **Connected** 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 o 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 um e-mail "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, `-.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 Test passa, mas nunca aparecem dados reais | Acedeu a caminhos que devolvem 404 numa implementação estática | Os 404 em implementações apenas estáticas são servidos a partir da edge cache da Vercel sem invocar o drain. Visite um caminho conhecido 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 continua a mostrar **Connected** | A página está a mostrar um estado desatualizado | Faça uma atualização forçada 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 do 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 atualizar antes de instalar. A Vercel cobra a saída do drain a aproximadamente 0,50 $ por GB transmitido, cobrado na sua fatura da Vercel. Para sites com pouco tráfego, isto é normalmente menos de 1 $ por mês. Para sites com muito tráfego, reduza o custo de duas formas: limite a instalação a **Specific Projects** apenas ao 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. O proprietário não é obrigatório. Configurar integrações faz parte das responsabilidades padrão da função de Membro ([funções de acesso da Vercel](https://vercel.com/docs/rbac/access-roles)). **No AirOps:** o utilizador que concluir a instalação tem de ter sessão iniciada no AirOps e ser membro do espaço de trabalho de destino, e qualquer função do AirOps funciona. #### 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 no momento da instalação e não o principal em tempo de execução. Pode cumprir 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 espaço de trabalho AirOps. Use a função com menor privilégio que o seu espaço de trabalho oferecer. 2. Inicie sessão como esse utilizador uma vez e conclua a instalação OAuth. 3. Após a conclusão da instalação, esse utilizador não tem autoridade em tempo de execução. A integração continua a autenticar-se através do token de API do espaço de trabalho descrito abaixo. Pode remover o utilizador do espaço de trabalho depois, se a sua política de segurança o exigir; a integração continuará a funcionar. O mesmo padrão aplica-se do lado da Vercel: um utilizador Vercel dedicado com a função de Membro 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 é feita em dois níveis: * **assinatura HMAC-SHA1** do corpo do pedido, com chave gerada por um segredo de drain por instalação gerado pelo AirOps no momento da instalação. A Vercel envia a assinatura no cabeçalho `x-vercel-signature` em cada entrega. * **token Bearer** no cabeçalho `Authorization` . O token é a **chave de API do AirOps do seu espaço de trabalho**, gravada na configuração do drain durante a instalação. Ambos os fatores estão ao nível do espaço de trabalho, não ao nível do utilizador. O utilizador que instala é registado apenas nos metadados de auditoria do AirOps. #### Rotação de token A chave de API do espaço de trabalho pode ser rodada na aplicação em **Account > Workspace > API Key** (requer a função de administrador do espaço de trabalho 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é a integração ser reinstalada a partir da Vercel (o que grava o novo token num novo drain). * A mesma chave de API do espaço de trabalho autentica outras APIs do AirOps (Public API, servidor MCP, SDK). Rodá-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, de 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 para 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 para a sua conta Vercel de forma contínua. Após o aprovisionamento inicial do drain, o AirOps recebe apenas 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 mais detalhes, contacte o Customer Success do AirOps e podemos orientar 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 **O nome da sua equipa Vercel ligada** na linha da Vercel. Isto leva-o para a 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 **Desligado** na próxima atualização da página. Os seus dados históricos da Vercel permanecem no AirOps depois de desligar. Para retomar o acompanhamento, clique em **Reinstalar na Vercel** na mesma linha. *** ### O que o AirOps rastreia Depois de conectado, o AirOps automaticamente: * **Ingere todos os pedidos servidos pela Vercel:** visualizações de páginas, 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.), obtenções de pesquisa de IA (PerplexityBot, OAI-SearchBot, etc.) e navegação de IA iniciada pelo utilizador (ChatGPT-User, Claude-User, etc.) * **Apresenta análises:** distribuição do 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=&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.