Istruzioni di installazione e configurazione

1. Requisiti

Il modulo è destinato a Magento 2 e a installazioni gestite tramite Composer.

Requisiti:

• progetto Magento 2 gestito tramite Composer,
• versione PHP compatibile con l’installazione Magento in uso,
• accesso a Magento CLI,
• OpenAI API key,
• processo Magento Message Queue consumer funzionante.

Pacchetto del modulo:

kowal/module-ai-email-theme-generator

Nome del modulo Magento:

Kowal_AiEmailThemeGenerator

2. Installazione

Aggiungi il repository Composer:

I dati di accesso al repository Composer, ovvero l indirizzo e-mail del cliente e il token di licenza, saranno inviati via e-mail dopo l acquisto. Sono disponibili anche nel pannello cliente dopo l accesso su kowal.store. Sostituisci TWOJ_EMAIL_KLIENTA con l indirizzo e-mail del tuo account e TWOJ_TOKEN con il token ricevuto. Esegui i comandi nella directory principale di Magento.

composer config repositories.kowal composer https://repo.kowal.store

Configura i dati di accesso al repository Composer Kowal:

composer config http-basic.repo.kowal.store "TWOJ_EMAIL_KLIENTA" "TWOJ_TOKEN"

Installa il modulo:

composer require kowal/module-ai-email-theme-generator

Abilita il modulo:

bin/magento module:enable Kowal_AiEmailThemeGenerator

Esegui l’aggiornamento di Magento:

bin/magento setup:upgrade

Svuota la cache:

bin/magento cache:flush

Per la modalità di produzione, esegui i comandi standard di deployment utilizzati nel progetto, ad esempio:

bin/magento setup:di:compile
bin/magento setup:static-content:deploy
bin/magento cache:flush

3. Queue Consumer

La generazione AI viene elaborata in modo asincrono tramite Magento Message Queue.

Avvia manualmente il consumer:

bin/magento queue:consumers:start kowal.ai_email.generate.consumer

Negli ambienti di produzione, configura il consumer sotto supervisor, systemd o un altro process manager utilizzato dall’hosting.

Il modulo crea attività nel pannello di amministrazione, ma la richiesta all’AI non verrà elaborata finché il consumer non è in esecuzione.

4. Autorizzazioni amministratore

Il modulo aggiunge risorse ACL:

Kowal_AiEmailThemeGenerator::root
Kowal_AiEmailThemeGenerator::jobs
Kowal_AiEmailThemeGenerator::generate
Kowal_AiEmailThemeGenerator::retry
Kowal_AiEmailThemeGenerator::cancel
Kowal_AiEmailThemeGenerator::apply
Kowal_AiEmailThemeGenerator::delete
Kowal_AiEmailThemeGenerator::settings

Per consentire all’amministratore di utilizzare il modulo, assegna le risorse appropriate in:

System > Permissions > User Roles

Per l’accesso completo, consenti la risorsa principaleAI Email Generatione tutte le risorse secondarie.

5. Posizione della configurazione

Vai a:

Stores > Configuration > AI Email Generation > AI Email Theme Generator

La sezione di configurazione contiene il gruppo:

General Settings

6. Campi di configurazione

Enabled

Tipo: Yes/No

Predefinito: No

Abilita o disabilita le funzioni del modulo.

Quando è impostato suNo:

• il modulo non dovrebbe creare attività di generazione AI,
• l’azione di generazione viene bloccata,
• l’amministratore dovrebbe prima configurare il modulo.

ImpostaYessolo dopo aver preparato l’API key e avviato il queue consumer.

API Provider

Tipo: Select

Predefinito: OpenAI

Definisce il provider AI utilizzato dal modulo.

L’implementazione attuale supporta:

OpenAI

Il campo esiste per consentire in futuro l’aggiunta di altri provider senza modificare il workflow dell’amministratore.

OpenAI API Key

Tipo: campo nascosto/crittografato

Memorizza la OpenAI API key utilizzata per la generazione.

Il valore viene crittografato da Magento utilizzando:

Magento\Config\Model\Config\Backend\Encrypted

Importante:

• non inserire l’API key direttamente nel codice,
• non effettuare commit delle chiavi ambiente,
• limita l’accesso a questo campo tramite ACL,
• usa una chiave con autorizzazioni adeguate al progetto.

OpenAI Model

Tipo: Select

Definisce il modello OpenAI utilizzato per la generazione.

Esempio:

gpt-4.1

L’elenco viene recuperato dinamicamente da OpenAI Models API usando l’API key configurata. Il modulo filtra la risposta limitandola agli identificatori dei modelli GPT e memorizza l’elenco in cache per un breve periodo, in modo da non richiamare l’API a ogni apertura della configurazione.

Se l’API key non è ancora stata salvata, il campo mostrerà un’opzione di fallback e chiederà all’amministratore di salvare la chiave.

Se OpenAI API è temporaneamente non disponibile, il campo mantiene il modello attualmente configurato, se possibile.

Usa un modello che supporti il tipo di dati di input richiesto:

• generazione testuale per prompt e contenuto del template,
• modello che supporta immagini, se vengono utilizzati progetti grafici di riferimento.

Il modello selezionato influisce sulla qualità del risultato, sul tempo di risposta e sul costo.

Request Timeout

Tipo: Number

Esempio di valore predefinito:

120

Tempo massimo in secondi consentito per la richiesta a OpenAI API.

Valori consigliati:

• 60per una breve generazione testuale,
• 120o più per una generazione HTML/CSS complessa,
• valori più alti solo se l’infrastruttura consente attività più lunghe in coda.

Il timeout riguarda l’elaborazione in background, non la richiesta del form amministrativo.

Maximum Retries

Tipo: Number

Esempio di valore predefinito:

2

Definisce quante volte il consumer può riprovare automaticamente un’attività di generazione non riuscita.

I tentativi sono utili in caso di errori temporanei, come:

• timeout API,
• errore temporaneo del provider,
• rate limit,
• problema di rete.

Gli errori permanenti, ad esempio una configurazione errata o una risposta AI non valida, dovrebbero essere verificati nei dettagli dell’attività.

Technical Prompt

Tipo: Textarea

Questo prompt viene applicato a ogni richiesta di generazione. Dovrebbe contenere regole tecniche che devono essere sempre rispettate.

Esempio:

You are an assistant generating Magento 2 email templates.
Return only JSON that matches the provided schema.
Keep Magento directives valid.
Do not invent Magento variables.
Do not add JavaScript.
Put CSS in template_styles unless inline styles are required for email compatibility.
Preserve required variables and add warnings when a requested change is risky.
When assets are provided, use only the URLs from the assets section, preserve alt text, apply target links to clickable images, use banners and icons according to their sort_order, and do not invent additional image URLs.

Usa questo campo per istruzioni stabili, come:

• mantenere le direttive Magento,
• preservare le variabili richieste,
• evitare JavaScript,
• restituire esclusivamente JSON,
• scrivere HTML compatibile con i client di posta,
• usare CSS nel campo corretto del risultato.

Non usare questo campo per istruzioni creative una tantum. A questo scopo serveAI Promptnel form del template.

Default User Prompt

Tipo: Textarea

Questo prompt viene mostrato per impostazione predefinita nella sezione AI dell’editor del template e-mail.

Esempio:

Improve this Magento email template while keeping all required Magento variables and directives valid.

L’amministratore può modificarlo prima di creare l’attività di generazione.

Usa questo campo per impostare un’istruzione predefinita pratica per le attività di generazione tipiche.

Allowed Design File Types

Tipo: Text

Esempio di valore predefinito:

png,jpg,jpeg,webp,html,htm,txt

Elenco delle estensioni file consentite per il progetto di riferimento opzionale, separate da virgole.

Esempi supportati:

• png
• jpg
• jpeg
• webp
• html
• htm
• txt

In produzione, usa un elenco il più possibile restrittivo. Non consentire tipi di file che non sono necessari nel processo.

Maximum Design File Size

Tipo: Number

Esempio di valore predefinito:

5242880

Dimensione massima del file di riferimento in byte.

Esempi:

• 1048576= 1 MB
• 5242880= 5 MB
• 10485760= 10 MB

File di grandi dimensioni aumentano la dimensione del payload e possono rallentare la generazione o superare i limiti del provider.

Automatically Apply Result

Tipo: Yes/No

Predefinito: No

Definisce se un risultato AI valido deve sovrascrivere immediatamente i campi nativi del template Magento.

Quando è impostato suYes, il consumer salva il risultato generato in:

• Template Name
• Template Subject
• Template Content
• Template Styles

Quando è impostato suNo, il risultato viene memorizzato nell’attività e l’amministratore può verificarlo prima di applicarlo manualmente.

Impostazione consigliata per la produzione:

No

L’approvazione manuale è più sicura, perché il risultato AI può essere tecnicamente corretto, ma richiedere comunque una revisione di brand, legale o di layout.

Keep Request and Response Payloads

Tipo: Yes/No

Predefinito: Yes

Definisce se il modulo salva i payload completi di richiesta e risposta nel record dell’attività.

Quando l’opzione è abilitata, i dettagli dell’attività possono mostrare:

• snapshot del template inviato all’AI,
• variabili disponibili,
• prompt,
• metadati del progetto di riferimento,
• risposta AI.

È utile per il debug e l’audit.

Negli ambienti di produzione, verifica i requisiti di privacy prima di abilitare questa opzione. Il modulo non dovrebbe inviare dati reali dei clienti all’AI, ma i payload possono comunque contenere contenuti dei template sensibili dal punto di vista aziendale.

Retention Days

Tipo: Number

Esempio di valore predefinito:

30

Definisce per quanto tempo devono essere conservate le vecchie attività.

Questo valore documenta la policy di retention prevista. Il progetto può utilizzarlo per implementare una pulizia periodica in base ai requisiti operativi.

7. Esempio: generazione del template New Order Confirmation for Guest

Questo esempio descrive il processo completo di generazione di un template e-mail Magento migliorato per:

New Order Confirmation for Guest

Passaggio 1: configura il modulo

Vai a:

Stores > Configuration > AI Email Generation > AI Email Theme Generator

Imposta:

Enabled = Yes
API Provider = OpenAI
OpenAI API Key = <your OpenAI API key>
OpenAI Model = gpt-4.1
Request Timeout = 120
Maximum Retries = 2
Automatically Apply Result = No
Keep Request and Response Payloads = Yes

Salva la configurazione e svuota la cache, se Magento lo richiede.

Passaggio 2: avvia il queue consumer

Esegui:

bin/magento queue:consumers:start kowal.ai_email.generate.consumer

Durante i test, il processo dovrebbe rimanere sempre in esecuzione.

Passaggio 3: crea un template Magento nativo

Vai a:

Marketing > Communications > Email Templates

Fai clic su:

Add New Template

Nel campoTemplate seleziona:

New Order Confirmation for Guest

Fai clic su:

Load Template

Magento compilerà i campi nativi:

• Template Subject
• Template Content
• Template Styles

Imposta il nome del template, ad esempio:

New Order Confirmation for Guest - AI Draft

Salva il template.

Il processo di generazione AI richiede un template salvato, perché l’attività deve avere untemplate_id.

Passaggio 4: compila AI Prompt

Dopo il salvataggio, riapri il template se necessario. L’editor standard dei template e-mail Magento contiene la sezioneAI Email Generation.

Nel campoAI Prompt inserisci un’istruzione business, ad esempio:

Create a modern, clean transactional email for a premium fashion store.
Keep all Magento order variables and directives valid.
Improve the subject line and make the content easier to scan.
Add a clear order summary section, shipping information section, and customer support footer.
Use neutral colors, simple spacing, and email-client-safe HTML.

Significato di questo campo:

• descrive il risultato business atteso,
• riguarda solo una specifica attività di generazione,
• può contenere istruzioni relative a brand, tono di comunicazione, layout o contenuto,
• non dovrebbe contenere dati API né dati reali dei clienti.

Passaggio 5: aggiungi facoltativamente Design Reference

UsaDesign Referencese l’e-mail generata deve seguire una direzione visiva specifica.

File di esempio:

• order-email-reference.png
• brand-email-layout.webp
• email-layout.html
• design-notes.txt

Significato di questo campo:

• fornisce all’AI un contesto visivo o strutturale aggiuntivo,
• aiuta ad adattare il template al progetto grafico,
• è opzionale,
• deve rispettare i limiti di estensione e dimensione dei file.

Se il progetto di riferimento non viene aggiunto, l’AI userà solo il contenuto del template, le variabili, il prompt tecnico e il prompt utente.

Passaggio 6: aggiungi facoltativamente Error Screenshot

UsaError Screenshotse vuoi mostrare all’AI il problema attuale di rendering, layout o validazione del template.

Esempi:

• screenshot di un’intestazione allineata in modo errato,
• screenshot di un problema con il banner,
• anteprima dell’e-mail con spaziatura errata,
• screenshot da un client di posta che mostra un problema di responsività,
• screenshot di un messaggio di errore da uno strumento di test.

Questo campo viene passato all’AI come sezione JSON separata:

{
  "error_screenshot": {
    "type": "image",
    "filename": "email-rendering-error.png",
    "mime_type": "image/png",
    "content_base64": "...",
    "purpose": "current_error_context",
    "description": "Screenshot showing current rendering, layout, visual, or validation errors. Use it to understand what should be fixed. This is not a design reference."
  }
}

Significato di questo campo:

• mostra all’AI l’errore attuale da correggere,
• non è un progetto grafico né un modello dell’aspetto finale,
• aiuta l’AI a capire cosa attualmente non funziona,
• dovrebbe essere usato insieme a una descrizione chiara del problema inAI Prompt.

Esempio di prompt:

Use the attached error screenshot only to understand the current rendering issue.
Fix the spacing problem visible in the screenshot while preserving Magento variables.
Do not treat the screenshot as the target design.

Passaggio 7: aggiungi AI Assets strutturali

L’editor contiene l’areaAI Assets. Questi asset vengono salvati con il template Magento e passati all’AI come URL media frontend raggruppati.

Gruppi di asset disponibili:

Ogni asset può contenere:

Per banner e icone fai clic su:

Add Banner
Add Icon

Il modulo salva gli asset caricati nel Magento media storage e passa all’AI gli URL frontend pubblici nella struttura:

{
  "assets": {
    "logo": {
      "label": "Brand logo",
      "url": "https://example.com/media/ai_email_theme_generator/template_12/logo/logo.png",
      "alt": "Brand logo",
      "link": "https://example.com/",
      "sort_order": 0
    },
    "header_image": {
      "label": "Spring campaign header",
      "url": "https://example.com/media/ai_email_theme_generator/template_12/header/header.jpg",
      "alt": "Spring collection",
      "link": "https://example.com/spring",
      "sort_order": 0
    },
    "banners": [
      {
        "label": "Main promotion",
        "url": "https://example.com/media/ai_email_theme_generator/template_12/banner/banner.jpg",
        "alt": "20% off new collection",
        "link": "https://example.com/new",
        "sort_order": 10
      }
    ],
    "icons": [
      {
        "label": "Free delivery",
        "url": "https://example.com/media/ai_email_theme_generator/template_12/icon/delivery.png",
        "alt": "Free delivery",
        "link": "https://example.com/delivery",
        "sort_order": 10
      }
    ]
  }
}

Nei prompt fai riferimento direttamente a questi gruppi. Esempio:

Use the uploaded logo as the main brand mark.
Use the header image at the top of the email.
Place banners below the order summary using their sort order.
Use icons in a benefits row and link each icon to its target URL.
Always preserve alt text.

Passaggio 8: seleziona la generazione dopo il salvataggio

Abilita:

Generate with AI after saving

Significato di questo campo:

• Magento prima salva il template con l’azione nativa standard save,
• dopo un salvataggio corretto, il modulo crea un’attività di generazione AI,
• il progetto di riferimento caricato viene allegato all’attività,
• l’attività viene elaborata in modo asincrono dal queue consumer.

Se la checkbox non è selezionata, il salvataggio del template funziona esattamente come il salvataggio standard di Magento e non viene creata alcuna attività AI.

Passaggio 9: salva il template

Fai clic sul pulsante standard Magento:

Save Template

Dopo il salvataggio del template, il modulo crea un’attività di generazione.

A questo punto:

• il salvataggio nativo del template è completato,
• lo stato dell’attività inizia dapending,
• il queue consumer elabora l’attività in background.

Passaggio 10: controlla l’attività

Vai a:

Marketing > Communications > AI Email Generation Jobs

Apri l’attività creata.

Campi principali:

Stati tipici:

Passaggio 11: applica il risultato

SeAutomatically Apply Result = No, il risultato non viene salvato automaticamente nel template Magento.

Controlla:

• Template Name
• Template Subject
• Template Content
• Template Styles
• Warnings
• Request Payload
• Response Payload

Se il risultato è corretto, fai clic su:

Apply Result

Il modulo salverà i valori generati nei campi nativi del template Magento.

Passaggio 12: verifica il template e-mail nativo

Torna a:

Marketing > Communications > Email Templates

Apri il template e verifica che:

• Template Name sia stato aggiornato,
• Template Subject sia stato aggiornato,
• Template Content contenga l’HTML atteso e le direttive Magento,
• Template Styles contenga il CSS atteso,
• le variabili Magento richieste non siano state rimosse.

Invia un messaggio di test oppure avvia un flusso d’ordine di test secondo il processo QA standard del progetto.

Passaggio 13: invia un’ulteriore correzione all’AI

Dopo aver applicato il risultato tramiteApply Result, la versione attuale del template viene salvata nei campi nativi Magento. Ciò significa che la successiva richiesta AI si baserà su questa versione, non sul template originale.

Puoi perfezionare più volte lo stesso template:

1. Applica il risultato AI tramiteApply Result.
2. Riapri il template inMarketing > Communications > Email Templates.
3. Inserisci un nuovo prompt che descriva la correzione specifica.
4. Se il problema è visivo, aggiungiError Screenshot.
5. SelezionaGenerate with AI after saving.
6. Salva il template.
7. Controlla la nuova attività e applica il risultato, se è corretto.

Nelle correzioni successive, consideraAI Promptcome la descrizione della modifica da apportare alla versione attuale. È consigliabile indicare:

• cosa è attualmente errato,
• quale risultato deve essere raggiunto,
• quali elementi l’AI non dovrebbe modificare,
• se l’Error Screenshotallegato mostra un errore di rendering, un layout visivo, un problema di responsività o un messaggio di validazione.

Esempio di prompt per una correzione successiva:

Use the current saved template as the base.
Fix the spacing issue visible in the attached error screenshot.
Keep the current header layout, all Magento variables, and the existing Template Styles structure.
Do not redesign the whole email.

Questo workflow è utile quando la prima versione è vicina al risultato atteso, ma richiede la rifinitura di dettagli come spaziature, responsività, visibilità dei banner, posizione del logo o stile dei pulsanti.

Puoi ripetere questo ciclo molte volte. Ogni nuova attività crea una voce separata nella cronologia, quindi è possibile tornare ai prompt, ai payload e alle risposte AI precedenti per verificare quale istruzione ha portato a una specifica modifica.

8. Significato dei campi del payload AI

Il modulo invia all’AI un payload strutturale. Le sezioni più importanti sono:

template

Contiene lo stato attuale del template Magento:

• ID del template,
• nome del template,
• subject,
• content,
• styles,
• codice originale del template.

L’AI usa questa sezione come materiale di base per la generazione.

Importante: se in precedenza è stato applicato un risultato AI tramiteApply Result, la sezionetemplatecontiene già questa versione aggiornata. In questo modo, la generazione successiva può funzionare come correzione del template attuale.

variables

Contiene le variabili e le direttive Magento rilevate nel template.

L’AI dovrebbe preservare questi valori e non dovrebbe inventare variabili non supportate.

prompts

Contiene:

• technical- prompt tecnico globale dalla configurazione,
• user- prompt inserito nell’editor del template.

Il prompt tecnico protegge la struttura specifica di Magento. Il prompt utente descrive il risultato atteso per un singolo template.

design_reference

Contiene metadati opzionali e il contenuto del progetto di riferimento caricato.

La sezione è vuota quando non è stato caricato alcun file di riferimento.

error_screenshot

Contiene uno screenshot opzionale che mostra errori attuali di rendering, layout, visivi o di validazione.

Questa sezione includepurposeedescriptionper consentire all’AI di sapere che il file serve a comprendere il problema e non come modello del progetto finale.

La sezione è vuota quando non è stato caricato alcuno screenshot.

Per le correzioni successive, è consigliabile usareerror_screenshotinsieme a un prompt preciso che indichi cosa correggere e cosa non modificare. In questo modo l’AI può risolvere un problema specifico senza ricostruire l’intero template.

Esempio: dopo aver applicato il primo risultato AI, l’amministratore nota che in Gmail il banner si sovrappone alla sezione di riepilogo dell’ordine. Nella richiesta successiva allega uno screenshot di quella vista e inserisce un prompt che chiede solo la correzione delle spaziature e della larghezza del banner. Il payload contiene ancora l’attualeTemplate ContenteTemplate Styles, quindi l’AI lavora sull’ultima versione salvata.

assets

Contiene gli asset grafici strutturali salvati per il template:

• logo,
• header image,
• banners,
• icons.

Ogni asset contiene un URL media pubblico, label, alt text, target URL, sort order e filename.

L’AI dovrebbe usare questi URL durante la costruzione dell’HTML e non dovrebbe inventare indirizzi immagine aggiuntivi.

store_context

Contiene informazioni di base sul negozio, come:

• store ID,
• locale,
• base URL.

L’AI può utilizzarle per comprendere la lingua e il contesto, ma non dovrebbe ricevere dati reali di clienti o ordini.

9. Risoluzione dei problemi

L’attività rimane nello stato pending

Causa più probabile:

• il queue consumer non è in esecuzione.

Controlla:

bin/magento queue:consumers:start kowal.ai_email.generate.consumer

La pagina di configurazione mostra access denied

Controlla le autorizzazioni ACL per:

Kowal_AiEmailThemeGenerator::settings

Dopo aver modificato le autorizzazioni dell’amministratore, esci e accedi nuovamente.

La generazione termina con un errore di API key mancante

Controlla:

OpenAI API Key

Assicurati che il modulo sia abilitato e che la configurazione sia stata salvata nello scope corretto.

Il risultato AI ha stato completed, ma il template non è stato aggiornato

Controlla:

Automatically Apply Result

Se l’opzione è impostata suNo, apri l’attività e fai clic su:

Apply Result

La correzione successiva non considera il risultato precedente

Controlla se il risultato precedente è stato applicato tramite:

Apply Result

La generazione successiva si basa sul template Magento attualmente salvato. Se il risultato del job ha statocompleted, ma non è stato applicato, il job successivo continuerà a basarsi su una versione precedente del template.

La risposta AI è stata rifiutata

Il modulo valida il JSON restituito. Può rifiutare il risultato se:

• mancano campi obbligatori,
• i campi obbligatori hanno tipi non corretti,
• il nome del template, il subject o il content sono vuoti,
• il content contiene il tagscript,
• il risultato non è un JSON valido.

Controlla il messaggio di errore nell’attività e ripeti la generazione con un prompt più chiaro.

10. Impostazioni di produzione consigliate

Valori iniziali consigliati:

Enabled = Yes
Request Timeout = 120
Maximum Retries = 2
Automatically Apply Result = No
Keep Request and Response Payloads = Yes for testing, No or limited retention for production
Retention Days = 30

Usa l’applicazione manuale del risultato finché il team non avrà la certezza che i prompt, il modello selezionato e le regole di validazione producano template coerenti.