Smart Bundle Engine — Documentación

Presentación

Smart Bundle Engine analiza el historial de tus pedidos de WooCommerce para detectar los productos realmente comprados juntos, genera automáticamente los packs correspondientes y los muestra en la ficha de producto, el carrito y el email post-compra — con un control de margen que limita automáticamente el descuento si es necesario.

Instalación

1. Descarga el archivo df-smart-bundle.zip desde tu cuenta de cliente DataFirefly.
2. En tu administración de WordPress, ve a Plugins → Añadir nuevo → Subir plugin.
3. Selecciona el ZIP, haz clic en Instalar ahora y activa el plugin.
4. Un nuevo menú Smart Bundles aparece en la barra lateral de la administración.

Al activarse, el plugin crea 4 tablas dedicadas (df_sbe_cooccurrence, df_sbe_bundles, df_sbe_bundle_items, df_sbe_analysis_state) y programa el cron de análisis.

Inicio rápido

1. Ve a Smart Bundles → Análisis y haz clic en Ejecutar análisis ahora.
2. Una vez terminado el análisis, la tabla Principales afinidades de compra muestra las parejas detectadas con sus métricas (ocurrencias, confianza, lift).
3. Si la generación automática está activada (por defecto), los packs se crean automáticamente — revísalos en Smart Bundles → Packs.
4. Visita una ficha de producto en la tienda: el bloque «Comprado frecuentemente con» aparece bajo el resumen del producto.

Análisis de co-ocurrencia

El motor recorre los pedidos completados y en procesamiento dentro de la ventana de análisis configurada (180 días por defecto), en lotes de 200 pedidos. Para cada pedido con varios productos, todas las parejas se extraen y contabilizan.

Las tres métricas

• Ocurrencias — número de pedidos que contienen la pareja A+B.
• Confianza — P(B|A) en porcentaje: en qué porcentaje de los pedidos que contienen A encontramos también B. Una confianza de 20 significa que B aparece en el 20 % de los pedidos que contienen A.
• Lift — relación entre la frecuencia observada de la pareja y la frecuencia esperada si A y B fueran independientes. Un lift superior a 1 indica una afinidad real; superior a 2, una afinidad fuerte.

Programación

El análisis se ejecuta automáticamente vía WP-Cron (hook df_sbe_run_analysis). Cada ejecución procesa hasta 25 lotes de 200 pedidos y retoma en el siguiente disparo gracias a un cursor persistente — ningún pedido se procesa dos veces. El botón Restablecer estado vacía las tablas de análisis y empieza de cero.

Generación automática de packs

Tras cada análisis completo, el motor selecciona las parejas que superan tus umbrales y crea los packs correspondientes. Tres ajustes controlan la selección:

• Co-ocurrencias mínimas (3 por defecto) — número mínimo de pedidos con la pareja.
• Confianza mínima (10 % por defecto) — umbral por debajo del cual la pareja se ignora.
• Packs máx. por producto (3 por defecto) — evita sobresaturar un mismo producto.

Las parejas retenidas se clasifican por puntuación (lift × ocurrencias). Los packs creados automáticamente reciben el origen «Auto»; los packs existentes con los mismos productos nunca se duplican. Los packs manuales siempre se conservan en los re-análisis.

Gestión de packs

La pantalla Smart Bundles → Packs lista todos los packs con sus productos, descuento, margen mínimo, contextos de visualización, vistas y conversiones. Puedes filtrar por estado, origen (auto/manual) o búsqueda libre.

Crear o editar un pack

1. Haz clic en Nuevo pack o Editar en uno existente.
2. Busca y añade los productos (mínimo 2) — la cantidad de cada artículo es ajustable y el orden se reorganiza arrastrando y soltando.
3. Define el descuento (porcentaje o importe fijo) y el margen mínimo.
4. Marca los contextos de visualización deseados: ficha de producto, carrito, email.
5. La prioridad determina el orden de visualización cuando varios packs son elegibles (más alto = primero).

En un pack existente, una tabla de Vista previa de precios muestra en directo el subtotal, el coste estimado, el descuento solicitado vs aplicado, el precio final y el margen real.

Control de margen

Cada pack tiene un umbral de margen mínimo (en % del precio final). El motor calcula el precio mínimo correspondiente:

precio_min_final = coste_total / (1 − margen_min / 100)

Si el descuento solicitado empujara el precio final por debajo de este umbral, se limita automáticamente al descuento máximo compatible. El descuento mostrado en la tienda es, por tanto, siempre seguro.

Fuente del coste

El coste de cada producto se determina en este orden:

1. Meta de producto — la clave _df_cost_price por defecto, configurable en los ajustes (compatible con Cost of Goods y otros plugins de precio de coste).
2. Ratio de respaldo — para los productos sin coste indicado, se asume un porcentaje del precio de venta (50 % por defecto).

Visualización en tienda

Ficha de producto

El bloque se inserta en el hook woocommerce_after_single_product_summary con prioridad configurable (15 por defecto, justo antes de los productos relacionados). Muestra las miniaturas de productos unidas por «+», el subtotal tachado, el precio del pack y el botón de añadir en un clic.

Carrito

Las sugerencias aparecen bajo la tabla del carrito (woocommerce_after_cart_table). Los packs cuyos productos ya están todos en el carrito se ocultan automáticamente.

Email post-compra

Un bloque de sugerencia se inserta en los emails Pedido completado y Pedido en procesamiento (solo cliente), en variantes HTML y texto plano, con un enlace de retorno directo a la tienda.

Cada contexto se activa de forma independiente y su título es personalizable en los ajustes.

Aplicación del descuento

El plugin nunca modifica los precios de los productos. Cuando un pack se añade al carrito, cada artículo lleva un marcador interno; en cuanto todos los artículos del pack están presentes, el descuento se aplica como fee negativo de WooCommerce («Descuento pack»). Este enfoque:

• preserva los precios de línea y los informes de ventas;
• sigue siendo compatible con impuestos, envíos y cupones;
• retira automáticamente el descuento si se elimina un artículo del pack del carrito.

Seguimiento de rendimiento

Cada visualización de un pack incrementa su contador de vistas; cada pedido que contiene un pack completo incrementa sus conversiones (al pasar a estado «en procesamiento» o «completado», con protección contra el doble conteo). La tasa de conversión por pack se muestra en la lista de packs, y la pantalla Análisis presenta las estadísticas globales: pedidos analizados, parejas detectadas, packs activos, vistas y conversiones acumuladas.

Referencia de ajustes

Análisis de co-ocurrencia

• Ventana de análisis (días) — 180 por defecto. Pedidos completados y en procesamiento durante este periodo.
• Co-ocurrencias mínimas — 3 por defecto.
• Confianza mínima (%) — 10 por defecto.
• Generación automática de packs — activada por defecto.
• Packs máx. por producto — 3 por defecto.

Precios y margen

• Descuento por defecto (%) — 10, aplicado a los packs generados automáticamente.
• Margen mínimo por defecto (%) — 20.
• Clave meta del precio de coste — _df_cost_price.
• Ratio de coste de respaldo (%) — 50.

Visualización

• Contextos — ficha de producto / carrito / email, activables por separado.
• Prioridad del hook de la ficha de producto — 15 por defecto.
• Títulos — un título personalizable por contexto.

Multilingüe

El plugin incluye 5 idiomas (FR, EN, ES, DE, IT) en formato .po/.mo más un archivo .pot para tus propias traducciones (textdomain df-smart-bundle). Compatible con Polylang y WPML — el idioma mostrado sigue la configuración regional del sitio o del usuario.

Desinstalación

Desactivar el plugin solo retira el cron programado — tus datos se conservan. Eliminar el plugin (vía Plugins → Borrar) ejecuta uninstall.php, que suprime definitivamente las 4 tablas, todas las opciones y los metadatos de pedido creados por el plugin (compatible HPOS).

Solución de problemas

No se genera ningún pack

• Comprueba que el análisis se haya ejecutado: Smart Bundles → Análisis debe mostrar un número de pedidos analizados superior a cero.
• Baja los umbrales (co-ocurrencias mínimas, confianza mínima) si tu historial es reducido.
• Verifica que la generación automática esté activada en los ajustes.

El pack no aparece en la tienda

• El pack debe estar activo y el contexto correspondiente marcado.
• Un pack cuyo descuento calculado es cero (limitación de margen total) se oculta en la ficha de producto.
• En el carrito, un pack ya completo se oculta por diseño.
• Purga la caché de página si usas un plugin de caché.

El descuento aplicado es inferior al configurado

Es la limitación de margen en acción: el coste total del pack no permite el descuento solicitado sin bajar del margen mínimo. Revisa los costes de los productos o ajusta el umbral de margen del pack.

FAQ

¿Funciona el plugin con productos variables?

El análisis y los packs operan a nivel del producto padre. Las variaciones de un mismo producto se contabilizan juntas.

¿Puedo excluir algunos productos del análisis?

No en la versión 1.0.0 — simplemente elimina o desactiva los packs no deseados; no se recrearán si los eliminas tras desactivar la generación automática.

¿Son los packs compatibles con los cupones?

Sí. El descuento del pack es un fee negativo independiente de los cupones de WooCommerce; ambos se acumulan.

¿Cuál es el impacto en el rendimiento?

El análisis se ejecuta en segundo plano por lotes. En la tienda, las consultas de packs son ligeras (tablas indexadas) y los assets solo se cargan en las páginas de producto y carrito.