DataFirefly Advent Calendar: calendario de Adviento para PrestaShop
Instalación y actualización, ajustes y cron de recordatorios, modelos listos, casillas y códigos de descuento, premio instantáneo, vista previa, correos, sorteo, estadísticas y solución de problemas.
Instalación y actualización
Instala el módulo desde Módulos > Gestor de módulos > Subir un módulo enviando el archivo ZIP, o copia la carpeta dfadventcalendar en el directorio /modules/ de tu tienda y haz clic en Instalar. El mismo ZIP funciona de PrestaShop 1.7.8 a 9.x.
La instalación crea las tablas del módulo, registra sus hooks, crea la página del calendario (una dirección por idioma) y añade la pestaña Catálogo > Descuentos > Calendario de Adviento. Las imágenes de las casillas se guardan en /img/dfadventcalendar/, fuera de la carpeta del módulo.
Actualización desde la 1.0.0: sube el nuevo ZIP y PrestaShop ejecuta la migración. Se conservan calendarios, casillas, participantes y códigos. La dirección anterior de la página se mantiene en todos los idiomas para que los enlaces ya enviados por correo sigan funcionando.
Ajustes del módulo
La página de configuración del módulo (botón Configurar) reúne los ajustes comunes a todos los calendarios.
- Dirección de la página del calendario: una dirección por idioma, por ejemplo
/calendario-de-advientoen español y/advent-calendaren inglés. El módulo rechaza una dirección ya usada por otra página. El título SEO de la página se define en Parámetros de la tienda > Tráfico y SEO. - Zona horaria y hora de la tienda: las casillas se abren en esta zona horaria, sea cual sea la del visitante o la del servidor.
- Recordatorios por ejecución del cron: número máximo de correos enviados en cada llamada (150 por defecto).
- Conservar los datos al desinstalar: calendarios, casillas, participantes e imágenes se quedan en la base de datos, listos para una reinstalación.
- Reloj de prueba (solo en modo depuración): todo el calendario se comporta como si fuera la fecha y hora indicadas. El back office muestra un aviso mientras esté rellenado. No lo dejes nunca activo en una tienda en producción.
Recordatorio diario: tarea cron
Copia la dirección cron mostrada y prográmala cada 15 minutos en el panel de tu alojamiento:
*/15 * * * * curl -s "https://www.tu-tienda.es/module/dfadventcalendar/cron?token=TU_TOKEN" > /dev/null
El calendario funciona sin cron: solo los correos de recordatorio dependen de él. Se muestra la última ejecución, y la lista de lanzamiento del panel avisa si el cron se ha detenido.

Crear un calendario
Abre Catálogo > Descuentos > Calendario de Adviento. Lo más rápido es partir de un modelo: las fechas, el número de casillas, el tema y el título en todos tus idiomas ya están preparados. Solo queda rellenar las casillas.
- Calendario de Adviento, 24 casillas o 25 casillas con el día de Navidad, desde el 1 de diciembre;
- Los 12 días de Navidad, del 13 al 24 de diciembre;
- Semana del Black Friday, 7 casillas hasta el último viernes de noviembre;
- Cuenta atrás de evento, 10 casillas antes de un lanzamiento o una venta privada.
El botón Calendario en blanco o Nuevo calendario te deja elegir cada ajuste.

Fechas y apertura
- Fecha de la primera casilla y número de casillas (de 1 a 60): una casilla por día a partir de esa fecha.
- Hora de apertura de las casillas: 00:00 para medianoche, o una hora de cita como las 08:00. Antes de esa hora, la casilla del día anterior sigue siendo la del día.
Aspecto
Hay nueve temas: Bosque de abetos, Papel kraft, Escarcha, Noche de invierno, Bastón de caramelo y cuatro temas fuera de Navidad (Negro y oro, Black Friday, Pastel de primavera, Laguna de verano). La opción Colores personalizados activa cuatro colores. Hay tres estilos de casilla: puertas abatibles, cajas de regalo con lazo y mosaicos minimalistas. La decoración anima el fondo: nieve, estrellas, confeti o ninguna. Una vista previa en directo muestra el resultado mientras ajustas.
Con los tamaños variados, la cuadrícula se rellena sin huecos en 6 o 4 columnas. En el móvil pasa a 4 columnas regulares. Las animaciones se detienen para los visitantes que piden a su dispositivo reducir el movimiento.

Participación
- Correo obligatorio para abrir las casillas: si se desactiva, los visitantes abren libremente, pero los códigos personales y los juegos siguen reservados a los inscritos.
- Reservado a cuentas de cliente: solo participan los clientes conectados y sus códigos quedan vinculados a su cuenta. Es la mejor protección contra la recogida de códigos con direcciones desechables.
- Confirmar la dirección de correo (doble opt-in) y casilla de boletín opcional, sin marcar.
- Permitir abrir casillas pasadas: los códigos compartidos siguen entonces válidos hasta el final del calendario.
- Texto de consentimiento: añade el enlace a tu política de privacidad.
Configurar las casillas
El panel del calendario presenta las casillas como tarjetas: fecha, tipo, recompensa, código, aperturas, códigos desvelados y pedidos. Los filtros Por configurar, Con código, Premio instantáneo, Hoy y próximas y Pasadas, junto con la búsqueda, encuentran una casilla al instante. Cada tarjeta permite editar la casilla, abrirla en vista previa o activarla.

Tipos de casilla
- Mensaje: texto, imagen y botón opcional.
- Código de descuento: el código es el protagonista, en un ticket para copiar o añadir al carrito.
- Producto desvelado: ficha de producto con precio y botón de añadir al carrito.
- Premio instantáneo: el participante prueba suerte y gana la recompensa con la probabilidad que fijes.
Recompensa y código
Descuento en porcentaje, descuento en importe, envío gratuito, producto de regalo o una regla de carrito existente de la tienda, con sus propias condiciones. Para las recompensas creadas por el módulo:
- Código personal: se genera una regla de carrito de un solo uso al abrir la casilla. Se vincula a la cuenta del cliente si se conoce y vale hasta medianoche, más la validez adicional elegida.
- Mismo código para todos: una regla de carrito por casilla, sincronizada automáticamente. Deja el campo vacío para un código automático (prefijo, año y número, por ejemplo
ADVENT26-07). - Importe mínimo de pedido y limitación al producto desvelado opcionales.
Los botones casilla anterior y casilla siguiente encadenan la edición. ¿Con prisa? Rellenar las casillas vacías aplica un plan listo para usar, traducido a todos tus idiomas.
Premio instantáneo
Ajusta la probabilidad de ganar (de 1 a 100 %), el número de premios (0 para ilimitados) y el mensaje de derrota. El sorteo se hace en el servidor al abrir la casilla, una sola vez por participante. Volver a abrir la casilla da el mismo resultado. Cuando se han ganado todos los premios, los siguientes participantes ven el mensaje de derrota.

Previsualizar y lanzar
El panel reúne todo lo necesario para lanzar el calendario:
- Vista previa el: elige una fecha y abre el calendario tal como se verá ese día. Los códigos mostrados son ejemplos y no se guarda nada. Los enlaces de vista previa caducan a los 7 días.
- Lista de lanzamiento: calendario activo, casillas configuradas, cron de recordatorios y correos de la tienda.
- Más > Enviarme los correos de prueba: los cuatro correos (recordatorio, bienvenida, confirmación, enlace de acceso) llegan al empleado conectado, en su idioma.

Lo que ve el cliente
La página del calendario se abre con una cuenta atrás hasta la próxima casilla y la casilla del día destacada. Una vez inscrito, el participante ve su anillo de progreso, su racha de días seguidos y el interruptor del recordatorio diario.

Las casillas tienen cinco estados: hoy (halo animado), por recuperar, abierta (contenido visible), próxima (candado y fecha) y perdida. Una estrella señala las casillas de juego.

Al abrirla, una ventana presenta la sorpresa: producto con su precio, código en un ticket y botones Añadir a mi carrito y Copiar. Si el carrito está vacío, el código se guarda 14 días y se aplica al primer producto añadido.

El resumen Tus códigos lista los códigos obtenidos, con su validez y su estado (usado, caducado).

En el móvil, la cuadrícula pasa a 4 columnas regulares y los paneles se apilan.

Juego de premio instantáneo
Una casilla de juego permite al participante probar suerte. Si gana, recibe el código como en una casilla normal. Si no, ve el mensaje de derrota y podrá jugar en la próxima casilla de juego. A un visitante no inscrito se le invita a dejar su correo: una sola oportunidad por participante.

Banner de inicio y botón flotante
El banner aparece en la página de inicio durante el calendario y, si quieres, unos días antes del inicio. El botón flotante, que se activa en los ajustes del calendario, recuerda la casilla del día en todas las páginas. El visitante puede ocultarlo hasta el día siguiente. Para colocar el banner en otro lugar, añade {hook h='displayDfAdventCalendar'} a una plantilla de tu tema.

Cuentas atrás fuera de Navidad
El mismo módulo anima cualquier momento clave: semana del Black Friday, lanzamiento de una colección, rebajas, aniversario de la tienda. Elige un modelo de cuenta atrás, un tema como Negro y oro, mosaicos minimalistas y una hora de apertura. Antes del inicio, la página muestra la cuenta atrás hasta la primera casilla.

Recordatorios y correos
Cada día, a partir de la hora elegida (nunca antes de la apertura de las casillas), un correo breve anuncia la casilla del día a los participantes confirmados que aún no la han abierto. Un participante recibe como máximo un recordatorio al día, y ninguno el día de su inscripción: basta con el correo de bienvenida. Los correos llevan los colores del tema del calendario.

Se incluyen cuatro plantillas en ocho idiomas en mails/: dfadvent_reminder (recordatorio), dfadvent_welcome (bienvenida), dfadvent_confirm (confirmación de la dirección) y dfadvent_access (enlace de acceso). Un participante que vuelve a escribir su dirección recibe un enlace de acceso: el módulo nunca conecta a nadie solo por escribir una dirección, y una misma dirección no recibe más de un correo cada 2 minutos. Para personalizar las plantillas, cópialas en themes/tu-tema/modules/dfadventcalendar/mails/.

Participantes
La lista de participantes se filtra con un clic: confirmados, pendientes de confirmación, recordatorios activos, boletín, cuentas de cliente, ganadores del sorteo. Indica las casillas abiertas y los códigos obtenidos por cada uno, y se exporta en CSV.

Sorteo final
En los ajustes del calendario, fija el número mínimo de casillas abiertas para participar (0 desactiva el sorteo) y describe el premio. El panel indica el número de participantes que pueden participar. El botón Sortear un ganador elige al azar entre los participantes confirmados que cumplen la condición, excluyendo a los ganadores anteriores. Cada sorteo queda registrado.
Un sorteo y un juego de premio instantáneo están sujetos a la normativa sobre concursos promocionales. Publica unas bases legales en tu tienda antes del lanzamiento.
Estadísticas
El panel muestra los participantes (confirmados, con cuenta de cliente), las casillas abiertas y la media por participante, los códigos desvelados y la proporción de códigos personales usados, los pedidos válidos realizados con un código, la facturación sin IVA de esos pedidos y los recordatorios activos. El gráfico de actividad muestra, casilla por casilla, las aperturas y las inscripciones del día.
Si Google Tag Manager está presente, el módulo envía estos eventos al dataLayer: dfadv_join, dfadv_door_open, dfadv_code_copy, dfadv_code_apply y dfadv_share.
El menú Más > Duplicar para el año siguiente copia el calendario y sus casillas con un año de diferencia, inactivo, sin participantes ni códigos.
Datos personales
- La casilla de consentimiento es obligatoria; la del boletín es independiente y está sin marcar.
- Cada correo de recordatorio contiene un enlace de baja en un clic.
- La dirección IP solo se guarda cifrada (hash), para limitar las inscripciones a 5 por hora y conexión.
- El módulo responde a las solicitudes de exportación (códigos incluidos) y de supresión de datos personales de PrestaShop.
Solución de problemas
No se envían los recordatorios
Revisa la lista de lanzamiento del panel: cron ejecutado en las últimas 24 horas y correos de la tienda activados. Los recordatorios salen a partir de la hora elegida y solo a los participantes confirmados que aún no han abierto la casilla del día.
La página del calendario devuelve un error 404
Comprueba que las URL amigables están activadas y vacía la caché. Si la dirección coincide con otra página, cámbiala en los ajustes del módulo.
Una casilla sigue cerrada en su día
Comprueba la hora de apertura del calendario y la zona horaria de la tienda (Internacional > Localización). Una casilla sin configurar o inactiva permanece cerrada.
El código no se añade al carrito
El mensaje mostrado es el de PrestaShop: importe mínimo no alcanzado, código caducado o código vinculado a otra cuenta de cliente. Si el carrito está vacío, el código queda en espera y se aplica al primer producto.
Compatibilidad
- PrestaShop 1.7.8 a 9.x, el mismo ZIP para todas las versiones.
- Temas Classic, Hummingbird y temas derivados.
- Multitienda (un calendario por tienda) y multidivisa (importes convertidos a la divisa del visitante).
- Arquitectura ModuleAdminController, sin dependencias de Composer.
- Módulo traducido al inglés, francés, español, alemán, italiano, neerlandés, polaco y portugués.