Contador de Ventas Shopware 6: guía de instalación y configuración

Esta guía cubre la instalación, la configuración y la personalización del plugin DfSalesCounter, que muestra en cada ficha de producto cuántas veces se ha vendido ya un producto, a partir de los pedidos reales de su tienda Shopware 6.

Requisitos

• Shopware 6.5.x, 6.6.x o 6.7.x en instalación autoalojada. Shopware Cloud (SaaS) no acepta plugins de servidor.
• PHP 8.1 o superior.
• Un tema storefront derivado del tema Storefront de Shopware, o un tema personalizado que conserve los bloques Twig estándar del bloque de compra.
• Se recomienda acceso por línea de comandos para la compilación del tema, aunque la instalación desde la administración también funciona.

Instalación

Subida del ZIP desde la administración

1. En la administración de Shopware, abra Extensiones y luego Mis extensiones.
2. Haga clic en Subir extensión y seleccione el archivo DfSalesCounter-1.0.0.zip.
3. Cuando el plugin aparezca en la lista, haga clic en Instalar y actívelo con el interruptor.
4. Recompile el tema desde Contenidos, Temas, seleccionando su tema y luego Recompilar tema. Este paso solo es necesario una vez, porque el plugin incluye una hoja de estilos de storefront.

Por línea de comandos

Coloque la carpeta DfSalesCounter en custom/plugins/ de su instalación y ejecute:

bin/console plugin:refresh
bin/console plugin:install --activate DfSalesCounter
bin/console theme:compile
bin/console cache:clear

En un entorno con una cadena de despliegue, la compilación del tema suele formar parte ya de los pasos estándar.

Configuración

La página de configuración se encuentra en Extensiones, Mis extensiones, botón … a la derecha de DataFirefly Sales Counter, y luego Configurar. El selector de la parte superior permite elegir el canal de venta al que se aplica la configuración: cada canal puede tener su propio umbral, su propio texto y su propia ubicación.

Pestaña General

• Activar el contador de ventas: interruptor principal. Desactivado, no se ejecuta ninguna consulta y no se muestra ningún distintivo.
• Modo de recuento: Cantidad vendida suma todas las cantidades pedidas del producto. Número de pedidos cuenta los pedidos distintos que han incluido el producto. El primer modo destaca el volumen, el segundo el número de clientes diferentes convencidos.
• Pedidos tenidos en cuenta: Todos los pedidos da la cifra bruta. Excluir pedidos cancelados descarta aquellos cuyo estado de máquina es cancelled. Solo pedidos pagados conserva únicamente los pedidos con una transacción en estado paid o paid_partially.
• Umbral mínimo antes de mostrar: por debajo de este valor no aparece ningún distintivo. El valor por defecto es 5. Un umbral de 0 se trata como 1, el distintivo nunca se muestra en un producto sin ventas.
• Periodo en días: limita el recuento a los últimos X días, según la fecha del pedido. El valor 0 significa un acumulado desde siempre.
• Sumar las ventas de todas las variantes: añade las ventas del producto padre y de todas sus variantes. Recomendado en un catálogo de moda o por tallas, conviene desactivarlo cuando cada variante corresponde a un uso distinto.
• Contar solo los pedidos del canal de venta actual: evita que una tienda B2B o un canal de exportación infle las cifras mostradas en la tienda al público general.

Pestaña Visualización

• Ubicación en la ficha de producto: Bajo el nombre del producto, Bajo el precio, o Bajo el bloque de compra, es decir al final del bloque, debajo del botón de añadir al carrito.
• Estilo visual: Distintivo muestra una píldora con borde, Texto simple muestra una línea sin recuadro, Banda muestra un bloque a ancho completo con una barra lateral de color.
• Icono: llama, carrito, marca de verificación o ninguno. Los iconos son SVG en línea, no se carga ninguna fuente de iconos.
• Color de acento: si se deja vacío, se usa el color primario del tema. Si se rellena, alimenta la variable CSS --df-sales-counter-accent en el elemento del distintivo.
• Separador de millares: espacio fino, coma, punto o ninguno. Útil en cuanto los contadores superan el millar.
• Texto personalizado: consulte la sección siguiente.
• Duración de la caché en segundos: 900 por defecto. El valor 0 desactiva la caché y consulta la base de datos en cada visualización de la ficha.

Personalizar el texto

Texto global desde la configuración

El campo Texto personalizado acepta una frase con el marcador %count% en el lugar donde debe aparecer la cifra. Ejemplo: Este modelo ha salido %count% veces este mes. Ese texto es común a todos los idiomas del canal de venta. Se sanea antes de mostrarse, lo que permite un marcado sencillo como <strong> pero bloquea cualquier script.

Textos por idioma mediante fragmentos

Deje vacío el campo Texto personalizado para controlar el texto idioma por idioma. Abra Ajustes, Tienda, Fragmentos de texto, y busque dfSalesCounter. Hay cuatro claves disponibles:

• dfSalesCounter.badge.quantitySingular y dfSalesCounter.badge.quantityPlural, usadas en modo cantidad vendida.
• dfSalesCounter.badge.ordersSingular y dfSalesCounter.badge.ordersPlural, usadas en modo número de pedidos.

Cada valor acepta el marcador %count%. Las traducciones española, inglesa, francesa, alemana e italiana vienen incluidas con el plugin. Un valor modificado en el gestor de fragmentos prevalece sobre el del plugin, incluso tras una actualización.

Cómo se calcula la cifra

El plugin lee las líneas de pedido de tipo producto, unidas al pedido y a su estado. El cálculo se realiza en una única consulta agregada, sin proceso en segundo plano y sin tabla dedicada.

• En modo cantidad, la consulta suma la columna de cantidades de las líneas de pedido.
• En modo pedidos, cuenta los identificadores de pedido distintos.
• Solo se tiene en cuenta la versión activa de los pedidos, las versiones de trabajo creadas durante un abono o una modificación de pedido se ignoran.
• Con la suma de variantes activada, el plugin resuelve primero la familia del producto mostrado, producto padre y variantes, y luego filtra sobre el conjunto de identificadores.

Si el resultado es inferior al umbral configurado, no se añade ninguna extensión al producto y la plantilla no muestra nada. El distintivo no existe por tanto en el HTML, lo que evita cualquier visualización residual mediante una regla CSS del tema.

Caché y frescura de la cifra

El resultado se guarda en el pool de caché de aplicación de Symfony, bajo una clave que combina el identificador del producto, el canal de venta y una firma de las opciones que influyen en el cálculo. Cambiar el modo de recuento, el alcance de los pedidos, el periodo o las opciones de suma modifica esa firma e invalida por tanto los valores anteriores de forma automática.

En cada pedido realizado, el plugin purga la caché de los productos contenidos en ese pedido, así como la de su producto padre. El contador refleja por tanto la venta sin esperar a que expire la duración configurada.

En un catálogo de tamaño moderado la duración de la caché puede fijarse a 0 sin consecuencias apreciables: la consulta actúa sobre columnas indexadas. En un catálogo grande con mucho tráfico, conserve una duración de varios minutos.

Personalización avanzada del renderizado

El plugin sobrescribe el bloque de compra de la página de producto y añade su distintivo en tres bloques Twig estándar, según la ubicación elegida: el bloque del nombre del producto, el bloque del contenedor de precio y el bloque del contenedor de compra. El distintivo lo renderiza una plantilla de componente dedicada, storefront/component/df-sales-counter/badge.html.twig, que expone dos bloques sobrescribibles, uno para el icono y otro para el texto.

Desde un tema o un plugin, la extensión es accesible en Twig sobre el producto de la página con el nombre dfSalesCounter. Expone la cifra bruta, la cifra formateada, la ubicación, el estilo, el icono, el color de acento, el texto personalizado y el modo de recuento. Puede así mostrar el contador fuera del bloque de compra, por ejemplo en una pestaña de información del producto, recuperando la extensión e incluyendo el componente.

Los estilos se definen en Resources/app/storefront/src/scss/base.scss en torno a las clases df-sales-counter, df-sales-counter__icon y df-sales-counter__text, con un modificador por estilo visual. Cualquier regla de su tema compilada después de la del plugin prevalece, sin necesidad de modificar el plugin.

Resolución de problemas

No aparece ningún distintivo

Compruebe en este orden: el plugin está activado, el interruptor de activación está en sí para el canal de venta correcto, el producto ha alcanzado el umbral configurado, y el alcance de pedidos elegido no excluye todos sus pedidos. Un umbral de 5 con un alcance Solo pedidos pagados en una tienda de pruebas cuyos pedidos nunca se marcan como pagados no producirá nunca ninguna visualización.

El distintivo aparece sin estilos

El tema no se ha recompilado tras la activación. Ejecute bin/console theme:compile o use el botón de recompilación en la administración.

La cifra parece congelada

La duración de la caché aún no ha expirado. Vacíe la caché de aplicación con bin/console cache:pool:clear cache.app, o fije temporalmente la duración a 0 para validar el cálculo.

El distintivo no aparece en el sitio correcto

Un tema muy personalizado puede haber eliminado o renombrado los bloques Twig del bloque de compra. Pruebe otra ubicación en la configuración, o incluya el componente manualmente en su plantilla recuperando la extensión del producto.

Actualización y desinstalación

Una actualización se realiza subiendo el nuevo ZIP y pulsando Actualizar, seguido de una recompilación del tema si la versión contiene cambios de estilo. La configuración se conserva.

Al desinstalar, una casilla propone conservar los datos de usuario. Desmarcada, se eliminan todas las claves de configuración del plugin. El plugin no crea ninguna tabla ni ejecuta ninguna migración, por lo que la desinstalación no deja nada en la base de datos más allá de su configuración.

Referencia de claves de configuración

Todas las claves llevan el prefijo DfSalesCounter.config. y se pueden manipular mediante la Admin API o el comando system:config:set:

• active, booleano
• countMode, valores quantity u orders
• orderScope, valores all, notCancelled o paid
• minThreshold, entero
• periodDays, entero
• aggregateVariants, booleano
• scopeToSalesChannel, booleano
• position, valores afterName, afterPrice o afterBuy
• style, valores badge, inline o banner
• icon, valores none, flame, cart o check
• accentColor, cadena hexadecimal
• thousandSeparator, valores space, comma, dot o none
• customText, cadena
• cacheTtl, entero en segundos