Tabela De Consulta De Agentes De Usuário De Código Aberto

Este repositório contém um conjunto de dados normalizados e curados de strings de user agent, armazenados como arquivos JSON e projetado para ser usado como uma tabela de consulta, a fim de derivar dados simples de user agent, como o cliente do user agent e o sistema operacional.

É usado como um componente do PageviewsOnline, mas é publicado aqui para uso geral.

O conjunto de dados é complementado por scripts utilitários simples para validar os dados e exportá-los para outros formatos ou linguagens de programação (como Java).

Filosofia do Projeto

O objetivo deste projeto não é fornecer um sistema de detecção de user-agent à prova de falhas ou perfeitamente preciso, mas sim uma solução prática, com o melhor esforço possível, que melhore com o tempo por meio do uso no mundo real e das contribuições da comunidade.

A detecção do agente do usuário é inerentemente imperfeita. Em vez de buscar precisão total, este projeto foca em ser:

• Prático
• Manutenível
• Transparente
• Bastante adequado para análises do mundo real e classificação

A precisão melhora ao longo do tempo por meio de atualizações selecionadas, uso no mundo real e contribuições da comunidade.

A análise heurística e as expressões regulares complexas costumam trocar a previsibilidade por ganhos marginais de precisão.

Este projeto favorece:

• Transparência acima da magia
• Dados curados, em vez de lógica opaca
• Resultados explicáveis em vez de detecção especulativa

Funcionalidades

• Conjunto de dados de agentes de usuário normalizados e revisados por humanos
• Comportamento de busca simples e previsível
• Formato baseado em JSON, fácil de inspecionar e de versionar
• Scripts de validação leves
• Exportar utilitários para outras linguagens (por exemplo, Java)
• Ativamente utilizado em um ambiente SaaS de produção

Strings Normalizadas de User Agent

O objetivo principal deste projeto é extrair informações de alto nível e estáveis a partir de strings de user agent de forma rápida e previsível.

Para isso, cada string do agente do usuário é normalizada antes do processamento. A normalização remove variações instáveis (como números de versão e diferenças de maiúsculas/minúsculas), mantendo o significado estrutural e semântico do agente do usuário.

As strings de User agent são normalizadas usando os seguintes passos:

• Substitua todos os dígitos numéricos (0-9) pelo caractere de reserva x. Isso remove o ruído causado por mudanças de versão, mantendo a estrutura e o comprimento dos tokens.
• Converta toda a string para minúsculas. Os tokens do agente do usuário são insensíveis a maiúsculas por convenção, e usar minúsculas garante buscas consistentes e confiáveis.

Por exemplo, a seguinte string do agente do usuário:

É normalizado para:

Essa abordagem de normalização facilita agrupar, comparar e manter ao longo do tempo os agentes do usuário, mantendo, ao mesmo tempo, precisão suficiente para a classificação de alto nível de clientes e sistemas operacionais.

Ao eliminar a variabilidade específica de versão e a variabilidade de maiúsculas/minúsculas, o processo de busca torna-se mais previsível e resiliente a futuras alterações do agente do usuário.

Formato de Dados

Cada entrada normalizada de agente do usuário inclui:

• id - A string normalizada do agente do usuário
• client_family - Classificação de alto nível do cliente (por exemplo: navegador, bot, aplicativo)
• os_family - Classificação de alto nível do sistema operacional

Os campos exatos podem evoluir ao longo do tempo, à medida que o conjunto de dados cresce.

Comportamento de Busca

A correspondência do agente do usuário é realizada contra strings normalizadas.

Correspondências exatas são preferidas; correspondências parciais ou heurísticas são intencionalmente evitadas para manter o comportamento previsível e fácil de depurar.

Contribuição

Contribuições são muito bem-vindas e ajudam a melhorar a qualidade geral e a precisão deste projeto.

A maneira mais eficaz de contribuir é adicionando ou atualizando entradas normalizadas de agentes do usuário no arquivo user_agents.json, juntamente com quaisquer dados de classificação relevantes.

Assim que suas alterações estiverem prontas, por favor envie um pull request contendo os dados necessários e/ou atualizações de código.

Mesmo informações parciais ou incompletas são úteis e apreciadas - cada contribuição ajuda a melhorar a cobertura e a confiabilidade a longo prazo.

Primeiros Passos (Guia Rápido)

O núcleo deste projeto é o conjunto de arquivos de dados JSON, localizados no diretório data/.

Para ajudar a manter e reutilizar esses dados, o repositório inclui um pequeno conjunto de scripts simples em Node.js que realizam validação básica e tarefas de exportação.

Comandos disponíveis:

• npm run test - Valida os dados JSON e verifica erros estruturais ou de consistência.
• npm run build - Constrói, classifica e exporta os dados normalizados para outros formatos de linguagem de programação (como Java) para facilitar a integração.

Estas ferramentas são intencionalmente simples, com foco na exatidão dos dados e na portabilidade, em vez de processamento complexo.

As Strings de User-Agent Não São Confiáveis

Extrair informações precisas a partir de strings de user-agent é inerentemente pouco confiável por várias razões:

• Não há padrão formal nem especificação que regule a estrutura ou o conteúdo das strings de user-agent
• Muitos agentes de usuário intencionalmente falsificam ou imitam outros agentes de usuário por questões de compatibilidade e legado

Por causa disso, é extremamente difícil determinar dados de user-agent de maneira totalmente precisa e consistente.

Esta biblioteca deve, portanto, ser vista como uma solução de melhor esforço, não como uma fonte de verdade garantida ou autorizada.

Com o uso contínuo e as contribuições da comunidade, a precisão pode melhorar ao longo do tempo.

Versionamento & Estabilidade

O conjunto de dados pode mudar ao longo do tempo conforme os agentes de usuário evoluem.

Classificações não são consideradas mudanças que quebrem a compatibilidade, mesmo entre versões menores.

Os consumidores devem considerar os resultados como meras indicações de esforço, não garantias contratuais.

Licença

Este projeto e seus dados são licenciados sob a Licença Apache 2.0 (Apache-2-0).

Uso comercial, modificação e redistribuição são permitidos.

Contribuições são bem-vindas e apreciadas.

Marca registrada

PageviewsOnline, Two-Dot-Oh, e quaisquer logótipos, nomes de serviços ou marcas associadas são marcas registadas da Two-Dot-Oh.

Este projeto é de código aberto; no entanto, o uso do nome PageviewsOnline ou de qualquer marca associada em conexão com um produto, serviço ou oferta não é permitido sem consentimento prévio por escrito.

Forks e obras derivadas devem usar um nome e identidade visual diferentes e não devem sugerir apoio ou filiação com PageviewsOnline ou Two-Dot-Oh.