Tabla de Búsqueda de User-Agent de Código Abierto

Este repositorio contiene un conjunto de datos normalizado y curado de cadenas de agentes de usuario, almacenado como archivos JSON y diseñado para usarse como una tabla de búsqueda con el fin de derivar datos simples del agente de usuario, como el cliente del agente de usuario y el sistema operativo.

Se utiliza como componente de PageviewsOnline, pero se publica aquí para uso general.

El conjunto de datos se complementa con scripts auxiliares simples para validar los datos y exportarlos a otros formatos o lenguajes de programación (como Java).

Filosofía del Proyecto

El objetivo de este proyecto no es proporcionar un sistema de detección de User-Agent infalible o perfectamente preciso, sino una solución práctica, con el mejor esfuerzo, que vaya mejorando con el tiempo a través del uso en el mundo real y las contribuciones de la comunidad.

La detección del agente de usuario es intrínsecamente imperfecta. En lugar de perseguir una precisión completa, este proyecto se centra en ser:

• Práctico
• Mantenible
• Transparente
• Lo suficientemente bueno para el análisis y la clasificación en el mundo real

La precisión mejora con el tiempo gracias a actualizaciones curadas, uso en el mundo real y contribuciones de la comunidad.

El análisis heurístico y las expresiones regulares complejas suelen sacrificar la predictabilidad a favor de mejoras marginales en la precisión.

Este proyecto favorece:

• Transparencia sobre la magia
• Datos seleccionados por encima de la lógica opaca
• Resultados explicables en lugar de detección especulativa

Características

• Conjunto de datos de agentes de usuario normalizado y revisado por humanos
• Comportamiento de búsqueda simple y predecible
• Formato basado en JSON, fácil de inspeccionar y control de versiones
• Scripts de validación ligeros
• Exportar utilidades para otros lenguajes (p. ej. Java)
• Utilizado activamente en un entorno SaaS de producción

Cadenas normalizadas de User Agent

El objetivo principal de este proyecto es extraer información de alto nivel y estable a partir de cadenas de agentes de usuario de una manera rápida y predecible.

Para apoyar esto, cada cadena de agente de usuario se normaliza antes de procesarse. La normalización elimina variaciones inestables (como números de versión y diferencias de mayúsculas/minúsculas) mientras se preserva el significado estructural y semántico del agente de usuario.

Las cadenas de User-Agent se normalizan con los siguientes pasos:

• Reemplaza todos los dígitos numéricos (0-9) por el carácter de marcador x. Esto elimina el ruido causado por cambios de versión, manteniendo la estructura y la longitud de los tokens.
• Convierte toda la cadena a minúsculas. Los tokens de User agent no distinguen entre mayúsculas por convención, y convertir a minúsculas garantiza búsquedas consistentes y confiables.

Por ejemplo, la siguiente cadena de agente de usuario:

Está normalizado a:

Este enfoque de normalización facilita agrupar, comparar y mantener los agentes de usuario a lo largo del tiempo, sin dejar de ser lo suficientemente preciso para una clasificación de alto nivel del cliente y del sistema operativo.

Al eliminar la variabilidad específica de la versión y la variabilidad de la capitalización, el proceso de búsqueda se vuelve más predecible y resistente a cambios futuros del agente de usuario.

Formato de datos

Cada entrada de agente de usuario normalizada incluye:

• id - La cadena de agente de usuario normalizada
• client_family - Clasificación de cliente de alto nivel (p. ej. navegador, bot, app)
• os_family - Clasificación de alto nivel del sistema operativo

Los campos exactos pueden evolucionar con el tiempo a medida que el conjunto de datos crece.

Comportamiento de Búsqueda

La coincidencia de agentes de usuario se realiza con cadenas normalizadas.

Se prefieren coincidencias exactas; se evitan intencionalmente coincidencias parciales o heurísticas para mantener el comportamiento predecible y fácil de depurar.

Contribuir

Las contribuciones son muy bienvenidas y ayudan a mejorar la calidad y la precisión generales de este proyecto.

La forma más efectiva de contribuir es añadiendo o actualizando entradas normalizadas de agentes de usuario en el archivo user_agents.json, junto con cualquier dato de clasificación relevante.

Una vez que sus cambios estén listos, por favor envíe una pull request con las actualizaciones de datos y/o código necesarias.

Incluso la información parcial o incompleta es útil y apreciada - cada contribución ayuda a mejorar la cobertura y la fiabilidad a largo plazo.

Primeros Pasos (Guía Rápida)

El núcleo de este proyecto es el conjunto de archivos de datos JSON, ubicados en el directorio data/.

Para ayudar a mantener y reutilizar estos datos, el repositorio incluye un pequeño conjunto de scripts simples de Node.js que realizan validaciones básicas y tareas de exportación.

Comandos disponibles:

• npm run test - Valida los datos JSON y verifica errores estructurales o de consistencia.
• npm run build - Construye, ordena y exporta los datos normalizados a otros formatos de lenguajes de programación (como Java) para una integración más sencilla.

Estas herramientas son intencionadamente mínimas, y se enfocan en la exactitud de los datos y la portabilidad, en lugar de un procesamiento complejo.

Las Cadenas de User-Agent No Son Confiables

Derivar información precisa de las cadenas de user-agent es intrínsecamente poco fiable por varias razones:

• No existe ninguna norma formal ni ninguna especificación que rija la estructura o el contenido de las cadenas de user-agent
• Muchos agentes de usuario intencionalmente suplantan o imitan a otros agentes de usuario por motivos de compatibilidad y legado

Por ello, es extremadamente difícil determinar los datos del user-agent de forma completamente precisa y consistente.

Por lo tanto, esta biblioteca debe verse como una solución de mejor esfuerzo, no como una fuente de verdad garantizada ni autorizada.

Con uso continuo y contribuciones de la comunidad, la precisión puede mejorar con el tiempo.

Versionado y Estabilidad

El conjunto de datos puede cambiar con el tiempo a medida que evolucionan los agentes de usuario.

Las clasificaciones no se consideran cambios incompatibles, incluso entre versiones menores.

Los consumidores deben considerar los resultados como indicios de un esfuerzo razonable, no como garantías contractuales.

Licencia

Este proyecto y sus datos se distribuyen bajo la Licencia Apache 2.0 (Apache-2.0).

El uso comercial, la modificación y la redistribución están permitidos.

Las contribuciones son bienvenidas y apreciadas.

Marca

PageviewsOnline, Two-Dot-Oh, y logotipos asociados, nombres de servicio o branding son marcas registradas de Two-Dot-Oh.

Este proyecto es de código abierto; sin embargo, el uso del nombre PageviewsOnline o cualquier marca asociada en relación con un producto, servicio u oferta no está permitido sin el consentimiento previo por escrito.

Las ramas y obras derivadas deben usar un nombre y una identidad de marca diferentes y no deben implicar respaldo por parte de PageviewsOnline o Two-Dot-Oh ni afiliación con ellos.