API de Personalización HTML para Segmentos
El endpoint /api/site/personalize-html permite generar y aplicar personalizaciones específicas al HTML de un sitio web basadas en segmentos de audiencia. Esta API es útil para adaptar dinámicamente la experiencia de usuario, el contenido y la interfaz de un sitio web según las características, preferencias y necesidades de diferentes segmentos de audiencia.
🎯 Personalización dinámica del HTML para cada segmento
Esta API analiza las características específicas de cada segmento de audiencia y genera modificaciones personalizadas al HTML del sitio, adaptando elementos visuales, estructura, contenido y funcionalidades para optimizar la experiencia de usuario de ese segmento particular. Ideal para implementar estrategias de personalización avanzada y marketing dirigido.
Características principales
- Personalización dinámica del HTML basada en segmentos específicos
- Modificación de elementos visuales, estructura y contenido
- Adaptación de la navegación y arquitectura de información
- Personalización de llamadas a la acción (CTAs) y mensajes clave
- Optimización de la experiencia de usuario según dispositivo
- Implementación de cambios mediante JavaScript o generación de HTML estático
- Soporte para A/B testing y experimentación
- Análisis de impacto de las personalizaciones aplicadas
Personalizador de HTML por Segmento
Prueba el API de personalización de HTML para segmentos con tus propios parámetros.
Parámetros de solicitud
| Parámetro | Tipo | Descripción | Valores posibles | Requerido |
|---|---|---|---|---|
url | string | URL del sitio a personalizar | URL válida | Sí |
segment_id | string | ID del segmento para el que se personalizará el HTML | Cualquier ID válido | Sí |
analysis_id | string | ID de un análisis estructural previo. Si se proporciona, el sistema usará este análisis en lugar de realizar uno nuevo | Cualquier ID válido de análisis previo | No |
personalization_level | string | Nivel de personalización a aplicar | minimal, moderate, extensive | No (default: moderate) |
target_elements | array | Tipos de elementos a personalizar | layout, navigation, content, cta, visuals, forms, all | No (default: all) |
implementation_method | string | Método de implementación de los cambios | js_injection, static_html, hybrid | No (default: js_injection) |
user_id | string | ID del usuario | Cualquier ID válido | No |
site_id | string | ID del sitio | Cualquier ID válido | No |
target_pages | array | URLs específicas a personalizar (si se omite, se aplica a todo el sitio) | Array de URLs | No |
device_type | string | Tipo de dispositivo para el que personalizar | all, mobile, desktop, tablet | No (default: all) |
aiProvider | string | Proveedor del modelo de IA | openai, anthropic, gemini | No |
aiModel | string | ID del modelo de IA | Depende del proveedor | No |
timeout | number | Tiempo máximo de espera en ms | 5000-120000 | No (default: 45000) |
include_preview | boolean | Si se debe incluir una vista previa del HTML personalizado | true, false | No (default: true) |
includeScreenshot | boolean | Si se debe incluir una captura de pantalla del resultado | true, false | No (default: true) |
test_mode | boolean | Si se debe ejecutar en modo de prueba sin aplicar cambios | true, false | No (default: true) |
Ejemplos de uso
Solicitud básica de personalización
{
"url": "https://ejemplo.com",
"segment_id": "seg_tech_enthusiasts",
"personalization_level": "moderate"
}Personalización específica de elementos
{
"url": "https://ejemplo.com",
"segment_id": "seg_senior_citizens",
"personalization_level": "extensive",
"target_elements": ["navigation", "forms", "visuals"],
"device_type": "desktop",
"implementation_method": "static_html"
}Personalización avanzada con configuración completa
{
"url": "https://ejemplo.com",
"segment_id": "seg_b2b_decision_makers",
"personalization_level": "extensive",
"target_elements": ["content", "cta", "layout"],
"implementation_method": "hybrid",
"target_pages": [
"https://ejemplo.com/pricing",
"https://ejemplo.com/features",
"https://ejemplo.com/contact"
],
"device_type": "all",
"aiProvider": "anthropic",
"aiModel": "claude-3-5-sonnet-20240620",
"include_preview": true,
"include_diff": true,
"include_performance_impact": true,
"test_mode": false
}Personalización usando un análisis estructural previo
{
"url": "https://ejemplo.com",
"segment_id": "seg_tech_enthusiasts",
"analysis_id": "analysis_56789",
"personalization_level": "moderate",
"target_elements": ["navigation", "content"],
"implementation_method": "js_injection"
}Respuesta
La respuesta incluye los siguientes campos:
| Campo | Tipo | Descripción |
|---|---|---|
url | string | URL del sitio personalizado |
segment_id | string | ID del segmento para el que se personalizó |
personalization_id | string | ID único de la personalización generada |
personalizations | array | Lista de personalizaciones aplicadas |
implementation_code | object | Código de implementación (JS o HTML) |
preview_url | string | URL de vista previa del sitio personalizado |
performance_impact | object | Análisis del impacto en rendimiento |
diff_summary | object | Resumen de los cambios realizados |
screenshots | object | Capturas de pantalla antes/después |
metadata | object | Metadatos de la solicitud y análisis |
Ejemplo de respuesta completa
{
"url": "https://ejemplo.com",
"segment_id": "seg_tech_enthusiasts",
"personalization_id": "pers_78901",
"personalizations": [
{
"id": "mod_12345",
"selector": "nav.main-navigation",
"operation_type": "replace",
"description": "Reorganización de la navegación principal para destacar secciones técnicas y recursos avanzados",
"before_html": "<nav class=\"main-navigation\">...</nav>",
"after_html": "<nav class=\"main-navigation\">...</nav>"
},
{
"id": "mod_23456",
"selector": ".product-description",
"operation_type": "append",
"description": "Ampliación de descripciones de producto con especificaciones técnicas detalladas y comparativas",
"before_html": "<div class=\"product-description\">...</div>",
"after_html": "<div class=\"product-description\">...</div>"
},
{
"id": "mod_34567",
"selector": ".primary-cta",
"operation_type": "replace",
"description": "Modificación de CTAs para enfatizar aspectos técnicos y de innovación",
"before_html": "<button class=\"primary-cta\">Comprar ahora</button>",
"after_html": "<button class=\"primary-cta\">Explorar especificaciones</button>"
}
],
"implementation_code": {
"type": "javascript",
"code": "document.addEventListener('DOMContentLoaded', function() {\n // Código de personalización para el segmento seg_tech_enthusiasts\n // Modificación de navegación\n const navElement = document.querySelector('nav.main-navigation');\n if (navElement) {\n // Código de modificación...\n }\n \n // Modificación de descripciones de producto\n const productDescriptions = document.querySelectorAll('.product-description');\n if (productDescriptions.length > 0) {\n // Código de modificación...\n }\n \n // Modificación de CTAs\n const ctaButtons = document.querySelectorAll('.primary-cta');\n if (ctaButtons.length > 0) {\n // Código de modificación...\n }\n});"
},
"preview_url": "https://preview.uncodie.com/personalization/pers_78901",
"performance_impact": {
"overall_score": 0.92,
"metrics": {
"load_time_impact": "+0.2s",
"first_contentful_paint_impact": "+0.15s",
"largest_contentful_paint_impact": "+0.25s",
"cumulative_layout_shift_impact": "+0.01",
"total_blocking_time_impact": "+0.1s"
},
"recommendations": [
"Considerar lazy loading para las imágenes técnicas adicionales",
"Optimizar el script de personalización para reducir el tiempo de bloqueo"
]
},
"diff_summary": {
"elements_modified": 12,
"content_blocks_changed": 8,
"styles_modified": 15,
"scripts_added": 1,
"total_changes": 36,
"change_complexity": "medium"
},
"screenshots": {
"before": "https://storage.uncodie.com/screenshots/original_12345.png",
"after": "https://storage.uncodie.com/screenshots/personalized_12345.png"
},
"metadata": {
"request": {
"timestamp": "2024-07-15T16:42:18Z",
"parameters": {
"url": "https://ejemplo.com",
"segment_id": "seg_tech_enthusiasts",
"personalization_level": "moderate",
"implementation_method": "js_injection",
"analysis_id": "analysis_56789"
}
},
"analysis": {
"modelUsed": "claude-3-5-sonnet-20240620",
"aiProvider": "anthropic",
"processingTime": "2.35 seconds",
"segmentDataSource": "seg_tech_enthusiasts (last updated: 2024-07-10)",
"siteScanDate": "2024-07-15T15:30:22Z",
"status": "success",
"personalizationStrategy": "adaptive_content_and_ui"
}
}
}Códigos de estado
| Código | Descripción |
|---|---|
| 200 | Solicitud exitosa |
| 400 | Parámetros inválidos |
| 404 | Segmento o sitio no encontrado |
| 422 | No se pudo generar personalización válida |
| 429 | Límite de solicitudes excedido |
| 500 | Error interno del servidor |
Consideraciones de implementación
Uso de analysis_id para optimización
El parámetro analysis_id permite reutilizar análisis estructurales previos, optimizando el proceso de personalización:
-
Rendimiento mejorado: Al evitar realizar un nuevo análisis completo utilizando
/api/site/analyze/structure, se reduce significativamente el tiempo de respuesta. -
Menor consumo de recursos: Aprovecha análisis ya realizados, reduciendo la carga en los servidores y los costos asociados.
-
Flujo de trabajo óptimo: Ideal para escenarios donde se prueba la personalización para diferentes segmentos sobre la misma estructura de sitio.
-
Consistencia: Garantiza que múltiples personalizaciones se basen en el mismo análisis estructural, evitando posibles discrepancias.
Métodos de implementación
La API ofrece tres métodos principales para implementar las personalizaciones:
-
JS Injection: Genera un script JavaScript que modifica el DOM en tiempo real cuando el usuario visita el sitio. Es la opción más flexible y no requiere modificar el código fuente del sitio.
-
Static HTML: Genera versiones estáticas del HTML personalizado que pueden ser servidas directamente a los usuarios del segmento. Ofrece mejor rendimiento pero requiere integración con el sistema de servicio del sitio.
-
Hybrid: Combina ambos enfoques, generando HTML estático para los elementos críticos y usando JavaScript para personalizaciones dinámicas o basadas en interacción.
Integración con sistemas de segmentación
Esta API está diseñada para integrarse con sistemas de segmentación de usuarios existentes. Puede utilizarse junto con:
- Cookies o localStorage para almacenar información de segmento
- Sistemas de gestión de consentimiento (CMP)
- Plataformas de CDP (Customer Data Platform)
- Herramientas de analítica web
Consideraciones de rendimiento
Las personalizaciones pueden afectar el rendimiento del sitio. Recomendaciones:
- Utilizar el campo
include_performance_impactpara evaluar el impacto antes de implementar - Considerar el uso de lazy loading para contenido personalizado pesado
- Implementar estrategias de caché para personalizaciones frecuentes
- Monitorear métricas Core Web Vitals después de implementar personalizaciones
Pruebas y optimización
Se recomienda:
- Comenzar con
test_mode: truepara evaluar las personalizaciones sin aplicarlas - Utilizar
personalization_level: minimalinicialmente y aumentar gradualmente - Implementar A/B testing para medir el impacto real en conversiones
- Refinar las personalizaciones basándose en datos de comportamiento del usuario
Almacenamiento en Redis
Los datos de los segmentos se almacenan en Redis utilizando sus tipos de datos nativos. Aquí hay un ejemplo de cómo se estructuran los datos:
# Variables
site_id="example_site"
segment_id="seg_tech_enthusiasts"
# Guardar metadatos como Hash
HSET site:${site_id}:segments:${segment_id}:metadata \
created_at "2024-07-15T16:42:18Z" \
updated_at "2024-07-15T16:42:18Z" \
version "1.0"
# Guardar una personalización de navegación como Hash
# El id único de la modificación es mod_12345
HSET site:${site_id}:segments:${segment_id}:personalizations:mod_12345 \
selector "nav.main-navigation" \
description "Reorganización de la navegación principal para destacar secciones técnicas" \
"html:before" "<nav class=\"main-navigation\">...</nav>" \
"html:after" "<nav class=\"main-navigation\">...</nav>"
# Guardar una personalización de contenido como Hash
# El id único de la modificación es mod_23456
HSET site:${site_id}:segments:${segment_id}:personalizations:mod_23456 \
selector ".product-description" \
description "Ampliación de descripciones de producto con especificaciones técnicas" \
"html:before" "<div class=\"product-description\">...</div>" \
"html:after" "<div class=\"product-description\">...</div>"
# Ejemplo más detallado de una personalización de contenido
# El id único de la modificación es mod_34567
HSET site:${site_id}:segments:${segment_id}:personalizations:mod_34567 \
selector ".product-features" \
description "Ampliación y reorganización de características técnicas del producto" \
"html:before" "<div class=\"product-features\"><h3>Características</h3><ul><li>Procesador rápido</li><li>Alta resolución</li><li>Batería duradera</li></ul></div>" \
"html:after" "<div class=\"product-features\"><h3>Especificaciones Técnicas</h3><ul><li>Procesador: Octa-core 2.4GHz, 4nm</li><li>Pantalla: AMOLED 2400x1080px, 120Hz</li><li>Batería: 5000mAh, carga rápida 65W</li><li>RAM: 12GB LPDDR5</li><li>Almacenamiento: 256GB UFS 3.1</li><li>GPU: Adreno 740</li></ul></div>" \
"additional_styles" "font-size: 14px; line-height: 1.5; color: #334455; padding: 12px; background-color: #f8f9fa;" \
"target_devices" "desktop,tablet" \
"priority" "high" \
"conditional_display" "true" \
"condition_script" "return window.innerWidth > 768 && document.referrer.includes('tech')" \
"js_enhancement" "document.querySelector('.product-features').addEventListener('click', function() { showDetailedSpecs(123); });"
# Guardar índices para búsqueda rápida de personalizaciones por tipo de elemento
SADD site:${site_id}:segments:${segment_id}:element_types:navigation mod_12345
SADD site:${site_id}:segments:${segment_id}:element_types:content mod_23456
# Guardar lista de todas las personalizaciones del segmento
SADD site:${site_id}:segments:${segment_id}:all_personalizations mod_12345 mod_23456
# Guardar reglas como Hash
HSET site:${site_id}:segments:${segment_id}:rules \
device_type "desktop,tablet" \
user_type "tech_enthusiast" \
"preferences:content_density" "high" \
"preferences:technical_level" "advanced"
# Guardar lista de segmentos del sitio como Set
SADD site:${site_id}:segment_list ${segment_id}La estructura en Redis utiliza los siguientes patrones de clave y tipos de datos:
- Metadatos: Hash con clave
site:{site_id}:segments:{segment_id}:metadata - Personalizaciones individuales: Hash con clave
site:{site_id}:segments:{segment_id}:personalizations:{modification_id} - Índices por tipo de elemento: Set con clave
site:{site_id}:segments:{segment_id}:element_types:{element_type} - Lista de todas las personalizaciones: Set con clave
site:{site_id}:segments:{segment_id}:all_personalizations - Reglas: Hash con clave
site:{site_id}:segments:{segment_id}:rules - Lista de segmentos: Set con clave
site:{site_id}:segment_list
Para recuperar los datos:
# Variables
site_id="example_site"
segment_id="seg_tech_enthusiasts"
# Obtener todos los metadatos de un segmento
HGETALL site:${site_id}:segments:${segment_id}:metadata
# Obtener todas las personalizaciones de un segmento
SMEMBERS site:${site_id}:segments:${segment_id}:all_personalizations
# Obtener una personalización específica por su ID
HGETALL site:${site_id}:segments:${segment_id}:personalizations:mod_12345
# Obtener todas las personalizaciones de un tipo específico de elemento
SMEMBERS site:${site_id}:segments:${segment_id}:element_types:navigation
# Luego obtener cada personalización individualmente
HGETALL site:${site_id}:segments:${segment_id}:personalizations:mod_12345
# Obtener reglas
HGETALL site:${site_id}:segments:${segment_id}:rules
# Obtener todos los segmentos de un sitio
SMEMBERS site:${site_id}:segment_listConsideraciones importantes:
-
Estructura de personalizaciones: Cada personalización tiene:
- Un ID único como
mod_12345 - Un tipo de elemento (navigation, content, cta, etc.)
- Un selector CSS para identificar el elemento en el DOM
- Un tipo de modificación (restructure, enhance, rephrase, etc.)
- Contenido HTML antes y después de la modificación
- Un ID único como
-
TTL (Time To Live): Se puede establecer para cada clave según necesidad
# Establecer TTL de 24 horas (86400 segundos)
EXPIRE site:${site_id}:segments:${segment_id}:metadata 86400-
Índices secundarios: Permiten buscar personalizaciones por tipo de elemento
- Útil para obtener todas las personalizaciones de navegación, CTAs, etc.
- Mejora la eficiencia de las consultas comunes
-
Eficiencia:
- Los Hash permiten acceder a campos específicos sin cargar todo el objeto
- Los Set son eficientes para operaciones de pertenencia y listas únicas