DF Audio Product — Lettura audio delle schede prodotto

Introduzione

DF Audio Product aggiunge un lettore audio a ogni scheda prodotto del suo negozio PrestaShop. Un clic su «Ascolta la descrizione» e il nome del prodotto, la descrizione breve e la descrizione completa vengono letti ad alta voce, alla velocità scelta dal visitatore.

Il modulo funziona con quattro motori di sintesi vocale: il motore del browser (gratuito, senza chiave API) e tre motori server premium (OpenAI, Google Cloud, ElevenLabs) i cui file MP3 vengono memorizzati in cache per contenere i costi.

Requisiti

• PrestaShop 8.0 a 9.x
• PHP 8.0 o superiore
• Estensione cURL attiva (solo per i motori server)
• Cartella var/ scrivibile da PHP (solo per i motori server)
• Nessuna dipendenza da Composer

Installazione

1. Nel back office, vada in Moduli > Gestore dei moduli.
2. Clicchi su Carica un modulo e trascini il file dfaudioproduct-1.0.0.zip.
3. Clicchi su Configura a installazione completata.

All’installazione il modulo crea automaticamente la tabella di cache, la scheda di amministrazione sotto Catalogo, la cartella di cache var/dfaudioproduct/ protetta da un file .htaccess, e si registra sugli hook necessari.

Scegliere un motore di sintesi vocale

Motore del browser (Web Speech API)

È il motore predefinito. La voce viene sintetizzata direttamente sul dispositivo del visitatore dal suo browser (Chrome, Edge, Safari, Firefox). Nessuna chiave API, nessun costo, nessun dato inviato a terzi e nessun file archiviato sul suo server.

Il modulo trasmette il testo della scheda al browser, che sceglie automaticamente una voce corrispondente alla lingua del visitatore. La qualità e il catalogo delle voci dipendono quindi dal sistema operativo del visitatore: ottimi su macOS e iOS, discreti su Windows e Android.

OpenAI TTS

Voci naturali di alta qualità. Inserisca la sua chiave API OpenAI, scelga un modello (tts-1 per la rapidità, tts-1-hd per la qualità massima, gpt-4o-mini-tts per il miglior compromesso) e una voce tra: alloy, echo, fable, onyx, nova, shimmer. Se il campo Voce è vuoto, viene usata alloy.

Google Cloud Text-to-Speech

Inserisca una chiave API Google Cloud con l’API Text-to-Speech attivata. Il campo Voce è facoltativo: lo lasci vuoto e il modulo dedurrà automaticamente il codice lingua dalla lingua del visitatore (fr-FR, en-US, es-ES, de-DE, it-IT). Per forzare una voce specifica, inserisca il suo nome completo, ad esempio it-IT-Neural2-A — il codice lingua viene allora dedotto dal nome della voce.

ElevenLabs

Inserisca la sua chiave API ElevenLabs e, obbligatoriamente, l’identificativo della voce (Voice ID) nel campo Voce. Lo troverà nella sua libreria di voci ElevenLabs. Il modulo usa il modello multilingue eleven_multilingual_v2, che gestisce nativamente le cinque lingue.

Configurazione

Attivare

Interruttore globale. Disattivato, il lettore scompare dalle schede prodotto e il controller di generazione audio smette di rispondere.

Velocità di riproduzione predefinita

Velocità applicata al primo caricamento della pagina: 0,75x, 1x, 1,25x, 1,5x o 2x. Il visitatore può poi alternare tra questi valori con il pulsante di velocità del lettore.

Numero massimo di caratteri

Lunghezza massima del testo letto, tra 200 e 20 000 caratteri (3 000 per impostazione predefinita). Il testo viene tagliato in modo pulito alla fine dell’ultima frase completa. Questa impostazione incide direttamente sul costo dei motori server, fatturati a carattere: un valore basso riduce la spesa, un valore alto legge integralmente le sue descrizioni.

Leggere la descrizione breve / la descrizione completa

Due interruttori indipendenti. Il nome del prodotto viene sempre letto per primo. Può leggere solo la descrizione breve (rapido, economico) o l’insieme.

Posizione di visualizzazione

• Sotto il blocco di acquisto (hook displayProductAdditionalInfo) — posizione consigliata, ben visibile sotto il prezzo e il pulsante di aggiunta al carrello.
• Tra le azioni prodotto (hook displayProductActions) — più integrata con i pulsanti del tema.

Il modulo è registrato su entrambi gli hook, ma mostra il lettore solo su quello selezionato: cambiare posizione non richiede alcun intervento nel posizionamento dei moduli.

Durata della cache (giorni)

0 = i file audio non scadono mai (consigliato). Un valore superiore elimina automaticamente i file generati da più di N giorni, alla generazione successiva. Utile se cambia voce o motore di frequente.

Funzionamento della cache

La cache riguarda solo i motori server; il motore del browser non genera alcun file.

1. Un visitatore clicca su «Ascolta la descrizione» per la prima volta.
2. Il modulo estrae il testo della scheda lato server, lo ripulisce dall’HTML e lo tronca secondo il suo limite di caratteri.
3. Calcola un’impronta univoca a partire da motore, modello, voce, lingua, negozio e dal testo stesso.
4. Se nessun file corrisponde, chiama l’API del motore, riceve l’MP3 e lo scrive in var/dfaudioproduct/.
5. Il file viene servito con un’intestazione ETag e un Cache-Control di un giorno. I visitatori successivi ricevono il file in cache, e i ricaricamenti di pagina restituiscono una risposta 304 senza ritrasmettere l’audio.

Conseguenza importante: paga al massimo una generazione per prodotto e lingua, non una per visita. Il suo costo dipende dalla dimensione del catalogo, mai dal traffico.

La velocità di riproduzione non entra nell’impronta: viene applicata dal browser sul file esistente. Un solo MP3 copre quindi tutte e cinque le velocità.

Invalidazione automatica

La cache audio di un prodotto viene svuotata automaticamente — in tutte le lingue e tutti i negozi — non appena quel prodotto viene modificato o eliminato, tramite gli hook actionObjectProductUpdateAfter e actionObjectProductDeleteAfter. Il nuovo audio viene generato al successivo ascolto, con il contenuto aggiornato. Nessuna azione manuale è necessaria dopo una correzione della descrizione.

Posizione dei file

Gli MP3 sono archiviati in var/dfaudioproduct/, nella radice di PrestaShop, volutamente fuori dalla cartella del modulo: un aggiornamento del modulo non distrugge quindi la cache. La cartella è protetta da un file .htaccess e da un index.php: i file sono accessibili solo attraverso il controller del modulo, mai in accesso diretto.

Gestione della cache nel back office

La pagina di configurazione mostra in alto un pannello di statistiche: numero di file in cache, spazio su disco occupato e numero totale di riproduzioni.

Il pulsante Sfoglia i file in cache apre la scheda Catalogo > DF Audio Product, che elenca ogni file con l’identificativo del prodotto, il nome, la lingua, il motore, la voce, la dimensione, il numero di riproduzioni e la data di generazione. Può eliminare un file, una selezione di file, o svuotare tutto con il pulsante Svuota tutto della barra degli strumenti.

Il pulsante Svuota la cache audio della pagina di configurazione ha lo stesso effetto: elimina i file dal disco e svuota la tabella. Gli audio verranno semplicemente rigenerati su richiesta.

Il lettore lato negozio

Il lettore si compone di un pulsante «Ascolta la descrizione», di una barra di avanzamento, di un contatore del tempo e di un pulsante di velocità.

• Motori server: la barra di avanzamento consente di spostarsi nell’audio, e il contatore mostra il tempo trascorso e la durata totale.
• Motore del browser: la barra di avanzamento è indicativa (avanza parola per parola) e il contatore è nascosto, poiché la Web Speech API non fornisce alcuna durata.

Il cambio di velocità durante la riproduzione è gestito in entrambi i casi. Con il motore del browser, non potendo la sintesi cambiare velocità al volo, il modulo la riavvia silenziosamente dall’ultima parola pronunciata — la ripresa è impercettibile. Un meccanismo di keep-alive aggira inoltre l’interruzione delle sintesi lunghe dopo una quindicina di secondi sui browser Chromium.

Il lettore si reinizializza automaticamente al cambio di combinazione in AJAX, ascoltando l’evento updatedProduct del tema.

Accessibilità

Il lettore è progettato per essere utilizzabile da tutti, nello spirito della direttiva europea sull’accessibilità (European Accessibility Act):

• Pulsante di riproduzione con stato aria-pressed che riflette la riproduzione in corso
• Area di annuncio aria-live per segnalare caricamento, riproduzione o errore agli screen reader
• Navigazione e attivazione interamente da tastiera, con anello di focus visibile
• Barra di avanzamento etichettata e utilizzabile da tastiera
• Rispetto della preferenza di sistema prefers-reduced-motion (animazione di caricamento rallentata)
• Aree tattili generose e layout adattato agli schermi piccoli

La lettura audio del contenuto prodotto costituisce una risposta concreta ai requisiti di accessibilità. La conformità complessiva del suo negozio dipende tuttavia da tutte le sue pagine — tema, processo di acquisto, contenuti editoriali.

Multilingua e multinegozio

Il testo viene estratto nella lingua del visitatore: ogni lingua produce quindi il proprio file audio, con la voce adeguata. In multinegozio, la cache è anche separata per negozio, il che consente descrizioni diverse da un negozio all’altro.

Le etichette dell’interfaccia del lettore («Ascolta la descrizione», «Pausa», «Riprendi», «Caricamento…») sono traducibili da Internazionale > Traduzioni > Traduzioni dei moduli.

Personalizzazione dello stile

Il lettore usa variabili CSS che può sovrascrivere dal foglio di stile del suo tema child, senza modificare il modulo:

.dfap-player {
  --dfap-accent: #2b6cb0;
  --dfap-accent-hover: #1f4f85;
  --dfap-muted: #718096;
  --dfap-bg: #ffffff;
}

Le classi utili sono .dfap-player (contenitore), .dfap-play (pulsante principale), .dfap-progress (barra), .dfap-speed (pulsante di velocità) e lo stato .dfap-is-playing.

Costi e buone pratiche

• Inizi dal motore del browser. È gratuito e permette di validare l’interesse della funzionalità presso il suo pubblico prima di qualsiasi investimento.
• Regoli il limite di caratteri. Passare da 3 000 a 1 200 caratteri dimezza la fattura API ed è ampiamente sufficiente per la maggior parte delle descrizioni.
• Legga solo la descrizione breve se le sue descrizioni lunghe sono molto dense o contengono tabelle tecniche poco adatte all’ascolto.
• Preriscaldi la cache visitando i suoi bestseller dopo un cambio di motore: i primi visitatori non dovranno attendere la generazione.

Risoluzione dei problemi

Il lettore non compare

Verifichi che il modulo sia attivo nella sua configurazione, che la posizione di visualizzazione corrisponda a un hook presente nel suo tema, e che la scheda contenga almeno venti caratteri di testo leggibile. Svuoti poi la cache di PrestaShop.

Il pulsante va in errore al clic (motori server)

Usi il pulsante Testa la connessione API: mostra il messaggio di errore esatto restituito dal fornitore. Le cause più frequenti sono una chiave API non valida o scaduta, una quota superata, una voce inesistente (in particolare un Voice ID ElevenLabs errato) o l’estensione cURL disattivata. Gli errori sono inoltre registrati in Parametri avanzati > Log, con il prefisso dfaudioproduct.

Non succede nulla con il motore del browser

Alcuni browser richiedono un’interazione dell’utente prima di autorizzare la sintesi vocale — qui è il caso, la riproduzione parte al clic. Verifichi poi che sia installata una voce per la lingua interessata sul sistema del visitatore. Su una postazione Windows senza pacchetto vocale italiano, il browser può non avere alcuna voce disponibile; il modulo ripiega allora sulla prima voce compatibile o resta silenzioso. Infine, la Web Speech API richiede una connessione HTTPS sulla maggior parte dei browser.

Errore di scrittura della cache

La cartella var/dfaudioproduct/ deve essere scrivibile dall’utente PHP. Verifichi i permessi della cartella var/ e lo spazio su disco disponibile.

L’audio non si aggiorna dopo la modifica di un prodotto

L’invalidazione è automatica. Se il vecchio audio persiste, si tratta della cache del browser del visitatore: essendo il file servito con un Cache-Control di un giorno, un ricaricamento forzato (Ctrl+F5) risolve il caso. Il nuovo ETag sostituisce poi il vecchio per tutti.

Disinstallazione

La disinstallazione elimina la tabella di cache, la scheda di amministrazione, tutte le impostazioni e l’intera serie di file MP3 generati, cartella var/dfaudioproduct/ compresa. Nessun residuo resta sul server.

Supporto

Una domanda, un bug, una richiesta di evoluzione? Contatti il team DataFirefly dalla pagina di supporto del sito. Indichi la sua versione di PrestaShop, la sua versione di PHP, il motore utilizzato e, se del caso, il contenuto del log degli errori.