DataFirefly Advent Calendar: calendario de Adviento para PrestaShop

Instalació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.

La instalación crea las tablas del módulo, registra sus hooks y añade la pestaña Catálogo > Descuentos > Calendario de Adviento. Las imágenes subidas para las casillas se guardan en /img/dfadventcalendar/, fuera de la carpeta del módulo, para conservarse tras una actualización.

Ajustes del módulo y tarea cron

La página de configuración del módulo (botón Configurar en el gestor de módulos) contiene tres ajustes y la URL cron.

Dirección de la página

Última parte de la URL del calendario, común a todos los idiomas (PrestaShop añade el prefijo de idioma, por ejemplo /en/). El valor por defecto depende del idioma principal de la tienda: /calendario-de-adviento en español, /advent-calendar en inglés, /calendrier-de-l-avent en francés. Las URL amigables deben estar activadas en PrestaShop.

Recordatorio diario: tarea cron

Los correos de recordatorio se envían mediante una tarea cron. Copia la URL mostrada y prográmala cada 15 minutos en el panel de tu alojamiento, por ejemplo:

*/15 * * * * curl -s "https://www.tu-tienda.es/module/dfadventcalendar/cron?token=TU_TOKEN" > /dev/null

En cada llamada, el módulo envía los recordatorios del día a partir de la hora configurada en el calendario, por lotes (150 por defecto, ajustable en «Recordatorios por ejecución del cron»). Cada participante recibe como máximo un recordatorio al día, y solo si todavía no ha abierto la casilla del día. La fecha de la última ejecución aparece bajo la URL; «Generar un nuevo token cron» inutiliza la URL anterior.

Crear un calendario

Abre Catálogo > Descuentos > Calendario de Adviento y haz clic en Nuevo calendario.

Fechas y casillas

• Fecha de la primera casilla: la casilla 1 se abre a medianoche ese día, en la zona horaria de la tienda, y luego una casilla al día.
• Número de casillas: 24 para un calendario clásico, 25 para incluir Navidad, de 1 a 31.
• Permitir abrir casillas pasadas: un participante que se perdió un día puede recuperarla hasta el final del calendario.

Al guardar, el módulo crea las casillas vacías. Permanecen cerradas hasta que las configures y las actives.

Aspecto

Hay cinco estilos: Bosque de abetos, Papel kraft, Escarcha, Noche de invierno y Bastón de caramelo. La opción Colores personalizados activa cuatro colores (fondo, texto, casillas, acento). Puedes añadir una imagen de fondo (JPG, PNG o WebP, 5 MB máx.), nieve cayendo, casillas mezcladas y tamaños variados.

Con los tamaños variados, el módulo decide qué casillas son anchas o grandes para que la cuadrícula se llene sin huecos en 6, 4 o 3 columnas según la pantalla. La última casilla siempre es la más grande.

Participación

• Correo obligatorio para abrir las casillas: si está desactivado, los visitantes abren libremente, pero los códigos personales siguen reservados a los inscritos.
• Confirmar la dirección de correo (doble opt-in): el participante hace clic en un enlace recibido por correo antes de abrir las casillas. Recomendado contra direcciones falsas.
• Casilla de boletín: añade una casilla opcional, sin marcar. La suscripción pasa por el boletín nativo del cliente o por el módulo ps_emailsubscription si está instalado.
• Texto de consentimiento: se muestra junto a la casilla obligatoria. Añade el enlace a tu política de privacidad.

Recordatorios

Activa el Correo de recordatorio diario y elige la Hora del recordatorio. El participante puede desactivar los recordatorios desde la página del calendario o desde el enlace de cada correo.

Banner de la página de inicio

El banner se muestra en la página de inicio durante el calendario y, si quieres, unos días antes con una cuenta atrás. Para colocarlo en otro lugar del tema, añade {hook h='displayDfAdventCalendar'} en una plantilla.

Configurar las casillas

Desde el panel del calendario, haz clic en Casillas y luego en Editar en cada casilla.

Tipos de casilla

• Mensaje: texto e imagen.
• Código de descuento: el código se destaca en la ventana de apertura.
• Producto desvelado: ficha de producto con precio y botón de añadir al carrito. Busca el producto por nombre o referencia.

El campo Gancho para el correo de recordatorio es la frase enviada en el recordatorio del día: invita a hacer clic sin desvelar la sorpresa.

Recompensa

Descuento en porcentaje, descuento en importe (impuestos incluidos, moneda por defecto), envío gratis o producto de regalo, con un importe mínimo de pedido opcional. En una casilla de producto, la opción «Aplicar el descuento solo al producto desvelado» limita el código a ese producto.

Tipo de código

• Código personal: se genera una regla de carrito de un solo uso cuando el participante abre la casilla. Se vincula a su cuenta de cliente si se conoce, y es válida hasta medianoche del día de apertura más la validez adicional elegida.
• Mismo código para todos: una sola regla de carrito por casilla, creada y sincronizada por el módulo. Deja el campo vacío para obtener un código automático (prefijo, año y número de casilla, por ejemplo ADVENT26-07) o escribe el tuyo. La validez cuenta desde la fecha de la casilla.

Previsualizar antes del lanzamiento

El botón Vista previa del panel abre el calendario tal como se verá un día concreto, y el icono del ojo de cada fila abre directamente la casilla de ese día. En vista previa, los códigos son ejemplos y no se guarda nada. La página no se indexa.

Más > Enviarme los correos de prueba envía los tres correos (recordatorio, bienvenida, confirmación) al empleado conectado, en su idioma.

Lo que ve el cliente

• Una cuenta atrás hasta la próxima casilla y, para los participantes, una barra de progreso.
• La casilla del día destacada. Las casillas se abren en 3D, con confeti la primera vez. Las animaciones se desactivan para los visitantes que piden menos movimiento.
• Un botón Añadir a mi carrito bajo cada código. Si el carrito está vacío, el código se guarda 14 días y se aplica con el primer producto añadido.
• El resumen Tus códigos bajo la cuadrícula, con la validez de cada código y su estado (usado, caducado).
• Un botón para compartir el calendario y un enlace en la cuenta de cliente.

Un participante ya inscrito que vuelve a escribir su dirección recibe un enlace de acceso por correo: el módulo nunca identifica a nadie solo por escribir una dirección.

Sorteo final

En los ajustes del calendario, el campo Sorteo final fija el número mínimo de casillas abiertas para participar (0 desactiva el sorteo), y Premio del sorteo final describe el premio mostrado en el calendario.

El panel Sorteo final indica cuántos participantes son elegibles. Sortear un ganador elige al azar entre los participantes confirmados elegibles, excluyendo a los ganadores anteriores. Cada sorteo queda registrado con el correo, las casillas abiertas, el número de elegibles y la fecha.

Panel y estadísticas

El panel muestra participantes, confirmados, recordatorios activos, altas en el boletín, pedidos realizados con un código y facturación sin IVA. Para cada casilla: aperturas, pedidos y facturación. Los participantes se exportan en CSV desde la lista Participantes.

Más > Duplicar para el año siguiente copia el calendario con sus casillas, textos e imágenes, adelanta la fecha un año y lo deja inactivo, sin participantes ni códigos.

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.

Correos

Se incluyen tres plantillas en ocho idiomas en mails/: dfadvent_reminder (recordatorio), dfadvent_confirm (confirmación y enlace de acceso) y dfadvent_welcome (bienvenida). Para personalizarlas sin perder los cambios al actualizar, cópialas en themes/tu-tema/modules/dfadventcalendar/mails/.

Datos personales

• La casilla de consentimiento es obligatoria; la del boletín es independiente y está sin marcar.
• Cada correo de recordatorio incluye un enlace de baja en un clic.
• La IP solo se guarda con hash, para limitar las inscripciones a 5 por hora y por conexión.
• El módulo responde a las solicitudes de exportación y borrado de datos personales de PrestaShop.

Solución de problemas

Los recordatorios no se envían

Comprueba la fecha de la última ejecución del cron en la configuración del módulo, que los recordatorios estén activados en el calendario y que la hora del recordatorio ya haya pasado. Solo reciben el recordatorio los participantes confirmados que no han abierto la casilla del día. Prueba el envío con «Enviarme los correos de prueba».

La página del calendario da un error 404

Comprueba que las URL amigables estén activadas y vacía la caché de PrestaShop. Si la dirección coincide con una página CMS o una categoría, cámbiala en la configuración del módulo.

El código no se añade al carrito

El mensaje mostrado es el de PrestaShop: pedido mínimo no alcanzado, código caducado o código personal vinculado a una cuenta de cliente sin sesión iniciada. En este último caso, el código queda en espera y se aplica al siguiente carrito cuando el cliente inicia sesión.

Una casilla sigue cerrada en su día

Las casillas se abren a medianoche en la zona horaria de la tienda (Internacional > Localización > Configuración). Comprueba también que la casilla esté activa: una casilla sin configurar permanece cerrada.

Compatibilidad

• PrestaShop 8.0 a 9.x, el mismo ZIP para ambas versiones.
• Temas Classic, Hummingbird y temas hijo.
• Multitienda y multiidioma.
• Arquitectura ModuleAdminController, sin dependencias Composer.
• Módulo traducido al inglés, francés, español, alemán, italiano, neerlandés, polaco y portugués.