DfPreorder SW — Guida completa

Shopware non offre alcuna funzione nativa «avvisami quando torna disponibile». DfPreorder SW colma questa lacuna: su ogni scheda di prodotto esaurito compare automaticamente un modulo di iscrizione, e il cliente riceve un avviso via e-mail — nella propria lingua — non appena il prodotto torna disponibile. Il plugin aggiunge anche una modalità preordine leggera (badge e data di spedizione prevista) e un modulo di amministrazione per seguire le iscrizioni. Un unico ZIP si installa su Shopware 6.5, 6.6 e 6.7. Questa guida copre l’installazione, la compilazione degli asset, il worker e l’attività pianificata, la configurazione, l’uso nello storefront, la modalità preordine, le e-mail, la Store API, la conformità al GDPR e la risoluzione dei problemi.

Come funziona il rilevamento del riassortimento

DfPreorder rileva i riassortimenti in due modi complementari, che convergono nella stessa routine idempotente — così i tuoi clienti vengono sempre avvisati, mai due volte:

• In tempo reale: un subscriber ascolta la scrittura dei prodotti e reagisce non appena cambia lo stock o lo stock disponibile.
• Scansione pianificata: un’attività pianificata viene eseguita ogni 15 minuti e recupera gli aggiornamenti di stock fatti via SQL diretto — tipicamente il decremento dello stock disponibile alla creazione di un ordine, o un’importazione ERP, che non attivano un evento applicativo.

Il modulo della lista d’attesa compare su una scheda di prodotto quando sono soddisfatte due condizioni: il prodotto è in modalità closeout e il suo stock disponibile è sceso a zero.

Installazione

1. Scarica l’archivio DfPreorder-v1.0.0.zip dal tuo account DataFirefly.
2. Copia la cartella decompressa DfPreorder in custom/plugins/, oppure installa lo ZIP da Amministrazione → Estensioni → Le mie estensioni → Carica estensione.
3. Installa e attiva il plugin:

   bin/console plugin:refresh
   bin/console plugin:install --activate DfPreorder

4. Compila gli asset dello storefront e dell’amministrazione (passaggio indispensabile — non viene fornito alcun dist):

   ./bin/build-storefront.sh
   ./bin/build-administration.sh

5. Svuota la cache:

   bin/console cache:clear

All’installazione, il plugin crea la tabella df_stock_notification, il set di campi personalizzati df_preorder sull’entità prodotto, due modelli di e-mail e l’attività pianificata. Alla disinstallazione senza conservazione dei dati, tutto viene rimosso.

Worker e attività pianificata

Affinché le e-mail vengano realmente inviate, due meccanismi devono essere in esecuzione — in produzione di solito è già il caso tramite l’admin-worker, systemd o cron:

• Il worker Messenger, che consuma il messaggio asincrono di riassortimento e invia le e-mail;
• Il pianificatore di attività, che attiva la scansione di sicurezza ogni 15 minuti.

bin/console messenger:consume async --time-limit=60
bin/console scheduled-task:run

Configurazione

Apri Estensioni → Le mie estensioni → DataFirefly Preordine e Lista d’attesa → ⋯ → Configura. Tutte le opzioni sono regolabili per canale di vendita tramite il selettore nativo in cima alla pagina.

• Attiva lista d’attesa: interruttore principale. Mostra il modulo sulle schede esaurite.
• Double opt-in: richiede una conferma via e-mail prima di attivare l’iscrizione (consigliato per il GDPR). Disattivato per impostazione predefinita.
• Consenti ospiti: se disattivato, solo i clienti registrati possono iscriversi.
• Elimina la voce dopo la notifica: minimizzazione dei dati — l’indirizzo e-mail viene cancellato una volta inviato l’avviso. Se disattivato, la voce viene conservata con stato «notificato».
• Notifiche per lotto: numero massimo di e-mail inviate per esecuzione (worker o scansione). 100 per impostazione predefinita.
• Mostra badge preordine: attiva il badge e la data di spedizione sui prodotti configurati per il preordine.

La lista d’attesa nello storefront

Quando un prodotto è esaurito (closeout + stock disponibile a zero), il modulo «Avvisami quando torna disponibile» compare automaticamente sotto il pulsante di acquisto. Il cliente inserisce la sua e-mail (precompilata se è connesso) e conferma.

• L’invio avviene tramite AJAX con un fallback completo senza JavaScript (messaggio flash + reindirizzamento).
• Un campo honeypot invisibile filtra i bot.
• Se il double opt-in è attivato, viene inviata un’e-mail di conferma; l’iscrizione si attiva solo dopo il clic sul link di conferma.
• Ogni e-mail può contenere un link di disiscrizione con un clic.

Modalità preordine

Il plugin crea un gruppo di campi personalizzati Preordine sull’entità prodotto. Apri un prodotto in Cataloghi → Prodotti, scheda Specifiche → Campi personalizzati, gruppo Preordine:

• Attiva preordine: interruttore di attivazione per questo prodotto.
• Data di spedizione prevista: la data mostrata nel badge.
• Nota di preordine: testo libero mostrato sotto il badge.

Quando il preordine è attivato e il badge è consentito nella configurazione, un badge ambra compare sopra il pulsante di acquisto con la data di spedizione prevista. Il rendering è isolato nel template del buy widget e resta sovrascrivibile.

E-mail e traduzioni

All’installazione vengono creati due modelli di e-mail, tradotti in cinque lingue — francese, inglese, tedesco, spagnolo e italiano:

• Di nuovo disponibile (df_preorder.back_in_stock): variabili productName, productUrl e l’oggetto product completo.
• Conferma di iscrizione (df_preorder.double_opt_in): aggiunge la variabile confirmUrl.

Ogni cliente viene avvisato nella lingua del negozio al momento dell’iscrizione: il plugin ricostruisce un contesto di lingua specifico dell’iscritto per risolvere il nome del prodotto tradotto e il modello corretto. L’URL del prodotto viene risolto tramite l’URL SEO canonico del canale e della lingua interessati.

I modelli restano completamente modificabili in Impostazioni → E-mail → Modelli e-mail. Cerca «back in stock» o «di nuovo disponibile» per trovarli.

Modulo di amministrazione

Il menu Marketing → Lista d’attesa e Preordine elenca tutte le iscrizioni: indirizzo e-mail, prodotto, stato (in attesa / confermato / notificato), data di iscrizione e data di notifica. L’eliminazione di massa è disponibile, utile per ripulire manualmente le vecchie iscrizioni.

Store API (headless / mobile)

Per negozi headless o app mobili, un endpoint Store API consente di iscrivere un cliente alla lista d’attesa:

POST /store-api/df-waitlist/subscribe
Content-Type: application/json
sw-access-key: <la-tua-chiave-di-accesso>

{
  "productId": "0189a1b2c3d4...",
  "email": "cliente@example.com"
}

Una richiesta valida restituisce una risposta di successo; un identificativo prodotto o un’e-mail non validi restituiscono un errore 400. Si applicano le stesse regole di configurazione (double opt-in, autorizzazione ospiti, ecc.).

Conformità al GDPR

• Gli indirizzi e-mail vengono raccolti unicamente per la notifica richiesta.
• Il double opt-in opzionale registra un consenso esplicito.
• Il comportamento predefinito elimina il dato personale non appena l’avviso è inviato.
• Un link di disiscrizione con un clic può essere inserito nei modelli di e-mail.
• La disinstallazione con eliminazione dei dati cancella la tabella, i modelli, i campi personalizzati e la configurazione.

Compatibilità 6.5 → 6.7 e risoluzione dei problemi

Il modulo non compare su un prodotto esaurito. Verifica che «Attiva lista d’attesa» sia selezionato per il canale di vendita corretto, che il prodotto sia in modalità closeout e che il suo stock disponibile sia zero. Svuota la cache dopo ogni modifica alla configurazione.

Le iscrizioni vengono registrate ma non parte alcuna e-mail. Il worker Messenger e/o il pianificatore non sono in esecuzione. Avviali manualmente per testare (vedi la sezione Worker), poi assicurati che vengano eseguiti in continuo in produzione.

Errore del servizio mail all’attivazione su Shopware 6.7. La classe di servizio mail astratta è stata sostituita da una classe concreta in 6.7. Il plugin gestisce questa differenza automaticamente tramite un compiler pass che crea l’alias adeguato; un semplice cache:clear ricompila il container se l’errore persiste dopo un aggiornamento.

L’e-mail parte nella lingua sbagliata. La lingua usata è quella del canale di vendita al momento dell’iscrizione. Verifica che il canale interessato abbia la lingua attesa e che il modello di e-mail disponga di una traduzione per essa.

Le e-mail sembrano inviate due volte. Non dovrebbe accadere: l’elaborazione è idempotente e marca (o elimina) ogni voce dopo l’invio. Se lo osservi, verifica di non eseguire più worker concorrenti senza la configurazione di trasporto adeguata.

Cosa succede alla disinstallazione? Con l’opzione di eliminazione dei dati, la tabella df_stock_notification, i due modelli di e-mail, il set di campi df_preorder, l’attività pianificata e la configurazione vengono rimossi. Senza di essa, tutto viene conservato per una reinstallazione successiva.