BXC-Stats

Plugin WordPress para captura de visitas, clicks e interacciones de formularios (CF7 y nativos) con reportes PDF, exportación CSV y envíos por email recurrentes.

Requisitos

• WordPress 6.2 o superior
• PHP 8.0 o superior
• MySQL 5.7 / MariaDB 10.3 o superior
• Contact Form 7 (opcional, solo si se desea trackear CF7)
• No requiere Dompdf — el motor PDF es autocontenido (clase BXC_Stats_PDF incluida).

Instalación

1. Sube la carpeta bxc-stats a wp-content/plugins/.
2. Activa el plugin desde el menú Plugins de WordPress.
3. Al activarse, se crean automáticamente las tablas:
   • {prefix}bxc_stats_visits (incluye columna ip_hash desde v1.1.0)
   • {prefix}bxc_stats_clicks
   • {prefix}bxc_stats_forms
   • {prefix}bxc_stats_sessions
4. Si actualizas desde una versión anterior a 1.1.0, la migración se ejecuta automáticamente la primera vez que se carga el admin: se añade la columna ip_hash a la tabla visits mediante ALTER TABLE.
5. Ve a BXC-Stats → Configuración para ajustar opciones de captura, seguridad y envíos.

PDF (sin dependencias externas)

El plugin incluye su propio motor PDF (includes/class-bxc-stats-pdf.php) que produce PDF 1.4 válido usando las fuentes base de PDF (Helvetica, Courier) con codificación WinAnsi — cubre todos los caracteres del español (á é í ó ú ñ ¿ ¡ —).

No necesitas instalar Dompdf ni ninguna otra librería. Las exportaciones PDF y los informes por email funcionan out-of-the-box.

Si tenías una instalación previa con Dompdf en lib/dompdf/, ya no se usa; puedes eliminar esa carpeta sin afectar la funcionalidad.

Características

Captura (frontend)

• Visitas y vistas por página — con identificación de visitas únicas por sesión (hash IP + User Agent + salt).
• IP del visitante (desde v1.1.0) — se almacena como hash SHA-256 + salt (GDPR-compliant) en la columna ip_hash. Visible en la vista de Registros → Visitas y en la exportación CSV.
• Clicks — identifica tag, id, class, text e href del elemento clickeado.
• Formularios nativos — captura campos (fields) antes del envío, sin interferir con el submit.
• Contact Form 7 — hook server-side en wpcf7_mail_sent para capturar el envío exitoso.
• UTM parameters — captura completa (utm_source, utm_medium, utm_campaign, utm_term, utm_content) + gclid, fbclid, msclkid.
• First-touch attribution — los UTMs se guardan en cookie (1 año) para atribuir conversiones a la primera visita.

Panel de administración

• Dashboard con KPIs (visitas/únicas/clicks/forms hoy, ayer, semana, mes) y gráfico de tendencia 30 días (Chart.js).
• Registros paginados con filtros: origen UTM, página (path), tipo/nombre de formulario, búsqueda dentro de fields por clave y valor (ej: buscar email = juan@...), rango de fechas.
• Vista de formularios mejorada (v1.1.0) — cada field del formulario se muestra como columna horizontal con su identificador como cabecera (ej: nombre, email, telefono, mensaje...). Control de altura con -webkit-line-clamp (máx 4 líneas) y scroll horizontal cuando hay muchas columnas. Hover sobre una celda expande el contenido sin romper el layout.
• Columna IP (hash) en visitas y formularios, con botón de copiar IP completa al portapapeles.
• Exportación CSV de cualquier vista filtrada (incluye BOM para Excel y columna ip_hash).
• Informe PDF generado con motor nativo autocontenido (sin Dompdf), con comparativa contra el mismo período del año anterior (KPIs, top páginas, top clicks, UTMs, formularios).
• Programación de emails: CSV o PDF recurrente (día/semana/mes/año) a múltiples destinatarios.
• Widget en el dashboard de WP con resumen rápido.

Seguridad

• Nonces en todas las peticiones AJAX (frontend y admin).
• Sanitización estricta: sanitize_text_field, sanitize_textarea_field, esc_url_raw, wp_strip_all_tags en todo input.
• Hash de IPs con SHA-256 + salt único del sitio (GDPR-compliant, no se almacena IP en texto plano).
• Rate limiting configurable (default 60 eventos/minuto por sesión).
• Detección de bots por User Agent (Googlebot, Bingbot, Facebook, Twitter, headless browsers, etc.).
• Capability-based access: requiere capability manage_bxc_stats (por defecto la tienen administradores; puede asignarse a roles personalizados con User Role Editor).
• Rol exclusión: ignora usuarios autenticados con roles configurados (default: administrator).
• Paths exclusión: no trackea /wp-admin, /wp-login.php, etc.
• Consentimiento de cookies: opcional respeta cookie de consentimiento (compatible con Cookiebot, Complianz, etc.).
• Archivos temporales protegidos: el directorio uploads/bxc-stats-tmp/ se protege con .htaccess (Deny from all).
• Sentencias preparadas: todas las consultas SQL usan $wpdb->prepare() con placeholders.
• Escapado de output: todos los datos mostrados pasan por esc_html(), esc_attr() o esc_url() según corresponda.

Retención y limpieza

• Retención configurable (default 365 días). El cron diario elimina registros más antiguos automáticamente.

Hooks y filtros disponibles

Action hooks

• bxc_stats_cron_daily — se dispara diariamente.
• bxc_stats_cron_weekly — se dispara semanalmente.
• bxc_stats_cron_monthly — se dispara mensualmente.
• bxc_stats_cron_yearly — se dispara anualmente.

Puedes engancharte para ejecutar lógica propia:

add_action( 'bxc_stats_cron_daily', function () {
    // Tu lógica aquí.
} );

Filtros

• cron_schedules — el plugin añade bxc_weekly, bxc_monthly, bxc_yearly.
• option_bxc_stats_settings — sanitización defensiva al leer settings.

Internacionalización

El plugin está en español por defecto. Los textos están wrappeados con __() y esc_html__() para traducción. El archivo .pot puede generarse con WP-CLI:

wp i18n make-pot wp-content/plugins/bxc-stats/ languages/bxc-stats.pot

Desinstalación

Al desinstalar (no desactivar), el archivo uninstall.php elimina:

• Las 4 tablas del plugin.
• Todas las opciones (bxc_stats_settings, bxc_stats_db_version, bxc_stats_activated_at).
• Los 4 cron jobs programados.
• El directorio temporal uploads/bxc-stats-tmp/.

Preguntas frecuentes

¿Funciona con caché (WP Rocket, W3 Total Cache)? Sí. El tracking es server-side para visitas (hook template_redirect) y AJAX para clicks/formularios, por lo que no depende de JS en caché. Sin embargo, si la página está cacheada, el hook template_redirect se ejecuta igualmente porque WP arranca aunque la salida esté cacheada por el plugin de caché (esto depende del plugin; algunos sirven HTML estático sin arrancar WP — en ese caso usa su hook de caché específico o mueve la captura al JS).

¿Cumple con GDPR? Sí. Las IPs se hashean con SHA-256 + salt del sitio, no se almacenan en texto plano. Los UTMs son datos de campaña, no personales. Los fields de formularios se almacenan tal como el usuario los envía (el responsable del sitio debe informar en su política de privacidad que estos datos se guardan con fines analíticos).

¿Puedo desactivar el hash de IP? La opción existe en Configuración → Seguridad, pero por cumplimiento GDPR el hash se mantiene activo por defecto. No se recomienda desactivarlo.

¿Cómo agrego más destinatarios a los emails? En Configuración → Email de reporte CSV / Informe PDF, separa los emails por coma: admin@midominio.com, marketing@midominio.com.

¿El PDF funciona sin Dompdf? Sí. Desde la v1.1.0 el plugin usa su propio motor PDF autocontenido (BXC_Stats_PDF). No requiere Dompdf, Composer ni ninguna instalación externa. Si actualizas desde una versión anterior, simplemente elimina la carpeta lib/dompdf/ si existía.

¿Cómo se muestran los fields de formularios en la vista de Registros? Cada field del formulario se muestra como columna horizontal independiente, con su nombre como cabecera (ej: nombre, email, telefono). La altura de cada celda está limitada a 4 líneas (~76px) con truncado automático; al pasar el ratón sobre una celda se expande para mostrar el contenido completo sin alterar el layout de la tabla. Si hay muchos fields distintos, la tabla tiene scroll horizontal.

Changelog

1.1.0

• PDF autocontenido: reemplazo de Dompdf por motor nativo BXC_Stats_PDF (sin dependencias externas).
• IP del visitante en visitas: nueva columna ip_hash en la tabla visits (migración automática vía ALTER TABLE).
• Columna IP visible en la vista de Registros → Visitas y Formularios, con botón de copiar hash completo al portapapeles.
• Vista de formularios rediseñada: los fields se muestran como columnas horizontales con control de altura (-webkit-line-clamp, máx 4 líneas, scroll horizontal cuando hay muchas columnas, hover expande sin romper layout).
• Exportación CSV: añade columna IP Hash para visitas y formularios.
• Limpieza de estilos CSS obsoletos (.bxc-toggle-fields, .bxc-fields-detail).
• Migración DB idempotente ejecutada en admin_init y en register_activation_hook.

1.0.0

• Versión inicial.
• Captura de visitas, clicks y formularios (CF7 y nativos).
• Panel admin con dashboard, registros paginados, informes PDF.
• Exportación CSV y PDF.
• Emails recurrentes (día/semana/mes/año).
• Seguridad: nonces, hash IPs, rate limiting, sanitización estricta.