Skip to Content
Uncodie Market Fit está disponible 🎉
Rest APIAgentsUXAPI de Análisis UX y Branding

API de Análisis UX y Branding 🎨

Esta API realiza un análisis específico de UX y branding utilizando únicamente el site_id para obtener la información del sitio desde la base de datos, completar automáticamente el objeto settings.branding y generar recomendaciones, problemas y oportunidades de experiencia de usuario.

🚀 Funcionalidades

  • Obtención automática de información del sitio desde la base de datos usando site_id
  • Análisis estructurado del sitio web
  • Completado automático del objeto settings.branding
  • Generación de recomendaciones UX categorizadas
  • Identificación de problemas y oportunidades
  • Cálculo de scores de UX y usabilidad
  • Guardado automático en base de datos

🧪 Prueba la API

🎨 Análisis UX & Branding Automático

🔍

Análisis Integral

Evalúa usabilidad, accesibilidad, diseño visual y rendimiento del sitio web.

🎨

Branding Automático

Extrae y estructura elementos de marca: colores, tipografía, personalidad y guidelines.

💡

Recomendaciones UX

Genera insights accionables categorizados por prioridad y esfuerzo de implementación.

📊

Scores Detallados

Califica aspectos específicos de UX con métricas cuantificables del 0 al 100.

Ejemplo de Análisis UX:

Entrada (Sitio Web)
URL: https://ejemplo.com
Site ID: uuid-del-sitio
User ID: uuid-del-usuario
Salida (Análisis UX)
• Branding completado
• 15 recomendaciones
• 8 problemas identificados
• 12 oportunidades
• Scores UX detallados
💡 Resultado: Análisis UX integral + Branding automático

API de Análisis UX y Branding

Realiza análisis integral de UX y completa automáticamente el objeto settings.branding con recomendaciones, problemas y oportunidades.

🎯 Características del Análisis:

  • Branding Pyramid: Extrae esencia, personalidad, beneficios, atributos, valores y promesa de marca.
  • Paleta de Colores: Identifica colores primarios, secundarios y de acento utilizados.
  • Tipografía: Analiza fuentes principales y secundarias del sitio.
  • Voz y Tono: Determina estilo de comunicación y rasgos de personalidad.
  • UX Scores: Califica usabilidad, accesibilidad, diseño, rendimiento y consistencia de marca.
  • Recomendaciones: Proporciona mejoras categorizadas por prioridad (alta/media/baja).
  • Problemas: Identifica issues críticos, altos, medios y bajos con impacto específico.
  • Oportunidades: Detecta áreas de mejora con potencial alto, medio o bajo.

📊 Scores UX Generados:

📈
Overall Score

Puntuación general de UX (0-100)

🖱️
Usability Score

Facilidad de uso y navegación

Accessibility Score

Cumplimiento de estándares de accesibilidad

🎨
Visual Design Score

Calidad del diseño visual

Performance Score

Rendimiento percibido

🏷️
Branding Consistency

Consistencia de elementos de marca

📋 Endpoints Disponibles

POST /api/agents/ux/analyze

Realiza un análisis completo de UX y branding del sitio web.

GET /api/agents/ux/analyze

Obtiene información sobre el servicio y sus capacidades.

🔧 Parámetros de Solicitud

Parámetros Obligatorios

ParámetroTipoDescripción
site_idstringUUID del sitio en la base de datos (único parámetro obligatorio)

Parámetros Opcionales

ParámetroTipoDescripciónDefecto
user_idstringUUID del usuario (se obtiene automáticamente del sitio)auto
options.timeoutnumberTiempo límite en ms (5000-60000)30000
options.includeScreenshotbooleanIncluir captura de pantallatrue
options.providerstringProveedor de IA (anthropic/openai/gemini)anthropic
options.modelIdstringID del modelo específico a usarclaude-3-5-sonnet-20240620
options.updateBrandingbooleanActualizar branding en BDtrue
options.languagestringIdioma del análisis (en/es)es

📊 Estructura de Respuesta

{ "success": true, "data": { "url": "https://ejemplo.com", "site_id": "uuid-del-sitio", "user_id": "uuid-del-usuario", "analysis_id": "uuid-del-análisis", "branding": { "brand_pyramid": { "brand_essence": "Esencia de la marca", "brand_personality": "Personalidad de la marca", "brand_benefits": "Beneficios principales", "brand_attributes": "Atributos clave", "brand_values": "Valores fundamentales", "brand_promise": "Promesa de marca" }, "brand_archetype": "hero", "color_palette": { "primary_color": "#000000", "secondary_color": "#666666", "accent_color": "#e0ff17" }, "typography": { "primary_font": "Arial, sans-serif", "secondary_font": "Times, serif", "font_size_scale": "medium" }, "voice_and_tone": { "communication_style": "profesional", "personality_traits": ["innovador", "confiable", "profesional"], "forbidden_words": ["cheap", "basic"], "preferred_phrases": ["premium quality", "customer-focused"] }, "brand_guidelines": { "do_list": ["Mantener consistencia visual"], "dont_list": ["Usar jerga técnica innecesaria"], "emotions_to_evoke": ["confianza", "profesionalismo"] } }, "ux_assessment": { "overall_score": 70, "usability_score": 75, "accessibility_score": 60, "visual_design_score": 80, "performance_score": 70, "branding_consistency_score": 65 }, "recommendations": [ { "category": "usability", "priority": "alta", "issue": "No se detectaron elementos de navegación claros", "recommendation": "Implementar una navegación principal visible", "impact": "Mejora significativa en la experiencia del usuario", "effort": "medio" } ], "problems": [ { "category": "accessibility", "severity": "medio", "description": "Posibles problemas de accesibilidad en imágenes", "location": "Elementos de imagen en el sitio", "userImpact": "Usuarios con discapacidades visuales pueden tener dificultades", "businessImpact": "Reducción en alcance y cumplimiento legal" } ], "opportunities": [ { "category": "branding", "potential": "alto", "description": "Desarrollar una identidad de marca más sólida", "expectedBenefit": "Mejor reconocimiento y lealtad de marca", "implementationComplexity": "media" } ], "timestamp": "2024-01-15T10:30:00Z", "processingTime": 15000 }, "message": "Análisis UX completado exitosamente" }

🎯 Categorías de Análisis

Recomendaciones UX

Las recomendaciones se clasifican en:

  • design: Aspectos visuales y estéticos
  • usability: Facilidad de uso y navegación
  • accessibility: Accesibilidad para usuarios con discapacidades
  • performance: Rendimiento y velocidad
  • branding: Consistencia de marca
  • content: Calidad y estructura del contenido

Prioridades

  • alta: Impacto significativo, debe implementarse pronto
  • media: Mejora importante, implementar en medio plazo
  • baja: Mejora menor, implementar cuando sea posible

Esfuerzo de Implementación

  • alto: Requiere cambios significativos
  • medio: Requiere modificaciones moderadas
  • bajo: Cambios menores o rápidos

💡 Ejemplos de Uso

Análisis Básico

const response = await fetch('/api/agents/ux/analyze', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ site_id: 'uuid-del-sitio' }) }); const result = await response.json(); console.log('Análisis completado:', result.data);

Análisis con Opciones Personalizadas

const response = await fetch('/api/agents/ux/analyze', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ site_id: 'uuid-del-sitio', options: { timeout: 45000, includeScreenshot: false, provider: 'openai', modelId: 'gpt-4-turbo', updateBranding: false, language: 'en' } }) }); const result = await response.json();

Procesamiento de Resultados

const { branding, ux_assessment, recommendations, problems, opportunities } = result.data; // Analizar branding console.log('Personalidad de marca:', branding.brand_pyramid.brand_personality); console.log('Colores principales:', branding.color_palette); // Revisar scores console.log('Score UX general:', ux_assessment.overall_score); console.log('Score de accesibilidad:', ux_assessment.accessibility_score); // Filtrar recomendaciones críticas const criticalRecommendations = recommendations.filter(r => r.priority === 'alta'); console.log('Recomendaciones críticas:', criticalRecommendations); // Identificar problemas severos const severeProblems = problems.filter(p => p.severity === 'crítico'); console.log('Problemas severos:', severeProblems);

🔄 Integración con Base de Datos

Actualización Automática del Branding

El endpoint actualiza automáticamente el objeto branding en la tabla settings:

UPDATE settings SET branding = $1, updated_at = NOW() WHERE site_id = $2;

Guardado del Análisis

El análisis completo se guarda en la tabla analysis:

INSERT INTO analysis ( site_id, url_path, structure, user_id, status, request_time, provider, model_id ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8);

📈 Métricas y Puntuación

Scores de UX

MétricaRangoDescripción
Overall Score0-100Puntuación general de UX
Usability Score0-100Facilidad de uso
Accessibility Score0-100Accesibilidad web
Visual Design Score0-100Calidad del diseño visual
Performance Score0-100Rendimiento percibido
Branding Consistency0-100Consistencia de marca

Factores de Puntuación

  • Problemas críticos: -20 puntos cada uno
  • Problemas altos: -10 puntos cada uno
  • Recomendaciones alta prioridad: -5 puntos cada una
  • Problemas por categoría: Penalizaciones específicas

🎨 Objeto Branding Completado

El endpoint extrae y estructura información de branding:

Brand Pyramid

  • Brand Essence: Esencia fundamental de la marca
  • Brand Personality: Personalidad y carácter
  • Brand Benefits: Beneficios principales ofrecidos
  • Brand Attributes: Atributos diferenciadores
  • Brand Values: Valores fundamentales
  • Brand Promise: Promesa de valor

Elementos Visuales

  • Color Palette: Colores primarios, secundarios y de acento
  • Typography: Fuentes principales y secundarias
  • Brand Assets: Variaciones de logo y uso

Voz y Tono

  • Communication Style: Estilo de comunicación
  • Personality Traits: Rasgos de personalidad
  • Forbidden Words: Palabras a evitar
  • Preferred Phrases: Frases preferidas

🔍 Casos de Uso

Auditoría UX Completa

Ideal para realizar auditorías integrales de experiencia de usuario:

// Análisis completo con actualización de branding const audit = await analyzeUX({ url: 'https://cliente.com', site_id: siteId, user_id: userId, options: { updateBranding: true, language: 'es' } }); // Generar reporte de recomendaciones const report = generateUXReport(audit.data);

Benchmarking Competitivo

Comparar múltiples sitios web:

const competitors = ['site1.com', 'site2.com', 'site3.com']; const results = await Promise.all( competitors.map(url => analyzeUX({ url, site_id, user_id })) ); // Comparar scores const comparison = results.map(r => ({ url: r.data.url, overall_score: r.data.ux_assessment.overall_score, usability_score: r.data.ux_assessment.usability_score }));

Seguimiento de Mejoras

Evaluar el impacto de cambios implementados:

// Análisis antes de los cambios const beforeAnalysis = await analyzeUX(params); // ... implementar cambios ... // Análisis después de los cambios const afterAnalysis = await analyzeUX(params); // Comparar mejoras const improvement = { overall: afterAnalysis.ux_assessment.overall_score - beforeAnalysis.ux_assessment.overall_score, usability: afterAnalysis.ux_assessment.usability_score - beforeAnalysis.ux_assessment.usability_score };

🚨 Manejo de Errores

Errores Comunes

ErrorDescripciónSolución
VALIDATION_ERRORParámetros inválidosVerificar formato de URL y UUIDs
ANALYSIS_ERRORError en el análisisRevisar conectividad y timeout
DATABASE_ERRORError en base de datosVerificar permisos y conexión

Códigos de Estado

  • 200: Análisis completado exitosamente
  • 400: Parámetros inválidos
  • 500: Error interno del servidor

📚 Documentación Relacionada

Last updated on