Thin Content Detector — Documentazione

DataFirefly Thin Content Detector scansiona automaticamente i tuoi prodotti, categorie e pagine CMS in tutte le lingue attive del tuo negozio. Rileva tre pattern tossici per la SEO — contenuto troppo povero, descrizioni duplicate e pagine dominate da boilerplate — e genera suggerimenti di arricchimento IA pronti da incollare. Questa guida copre installazione, configurazione, utilizzo quotidiano, pianificazione cron e risoluzione dei problemi.

Panoramica

Dal Helpful Content Update, Google sta retrocedendo attivamente le pagine con contenuti troppo brevi, troppo simili ad altre pagine o troppo dominati da elementi ripetuti. In un catalogo e-commerce, sono tipicamente le schede prodotto copiate dal fornitore, le categorie con due frasi generiche, o le varianti che condividono il 95 % della loro descrizione. Invisibile a occhio nudo su 500 prodotti — ma cumulato, è ciò che impedisce al tuo sito di posizionarsi.

I tre tipi di rilevamento

• Thin content — pagine al di sotto della soglia di parole configurabile. Tre livelli di gravità in base alla distanza dalla soglia (critica < 25 %, avviso 25–75 %, notifica 75–100 %).
• Duplicati — rilevamento in due passi: hash SHA1 per i duplicati esatti (gravità 3), poi similarità Jaccard ≥ soglia configurabile per i quasi-duplicati (gravità 2).
• Rapporto template / contenuto — identifica i token condivisi con le pagine sorelle (stessa categoria padre) e calcola la percentuale di token unici per pagina. Una pagina con 200 parole ma 90 % di boilerplate è tossica quanto una pagina di 30 parole.

Installazione

1. Carica lo ZIP del modulo tramite Moduli > Gestione moduli > Carica un modulo.
2. Clicca su Installa. Il modulo crea due tabelle (ps_dfthincontent_issue e ps_dfthincontent_scan) e una scheda amministrativa sotto Catalogo.
3. Accedi al modulo tramite Catalogo > Thin Content (DataFirefly).

Configurazione

Clicca sul pulsante Configurazione nella barra degli strumenti del modulo. Sono disponibili tre pannelli.

Soglie di rilevamento

• Parole minime prodotto — default 150. Qualsiasi prodotto la cui descrizione lunga + corta combinate contenga meno di 150 parole verrà segnalato.
• Parole minime categoria — default 100.
• Parole minime pagina CMS — default 250.
• Soglia di similarità Jaccard — default 85 %. Oltre questa soglia, due pagine sono considerate quasi-duplicate.
• Rapporto template minimo — default 30 %. Al di sotto, la pagina è considerata troppo dominata da boilerplate.

Obiettivi di scansione

• Scansiona prodotti (ON di default).
• Scansiona categorie (ON di default).
• Scansiona pagine CMS (ON di default).
• Riscansione automatica al salvataggio (OFF di default). Quando attivato, ogni salvataggio di un prodotto, categoria o pagina CMS attiva un retest mirato solo di quell’oggetto. Vedi in tempo reale se la tua riscrittura supera le soglie.

Configurazione IA

I suggerimenti di arricchimento utilizzano un endpoint compatibile con OpenAI (chat completions). Questo include un’ampia gamma di provider:

• OpenAI — endpoint https://api.openai.com/v1/chat/completions, modello consigliato gpt-4o-mini (≈ 0,001 € per suggerimento).
• Mistral AI — endpoint https://api.mistral.ai/v1/chat/completions, modello mistral-small-latest.
• Groq — endpoint https://api.groq.com/openai/v1/chat/completions, modello llama-3.3-70b-versatile. Molto veloce.
• Ollama in locale — endpoint http://localhost:11434/v1/chat/completions, qualsiasi modello scaricato. Costo zero.
• Anthropic tramite un proxy compatibile con OpenAI.

Parametri da compilare:

• Endpoint — URL completo verso /v1/chat/completions.
• Modello — identificativo del modello presso il provider.
• Chiave API — Bearer token. Memorizzata cifrata tramite il sistema di configurazione PrestaShop.
• Max tokens — default 600. Sufficiente per un suggerimento di arricchimento standard.

Utilizzo — Dashboard

La dashboard è la home page del modulo. Mostra:

• Tre contatori principali — totale problemi aperti, corretti, ignorati.
• Ripartizione per tipo di problema — thin / duplicate / template.
• Ripartizione per tipo di oggetto — prodotto / categoria / pagina CMS.
• Soglie attuali — promemoria dei valori configurati.
• Ultime 5 scansioni — data, durata, numero di oggetti analizzati.
• Pulsante “Avvia scansione completa” — attiva una scansione sincrona tramite AJAX. Un modale mostra l’avanzamento e il riepilogo alla fine.

Avviare una scansione

Clicca su Avvia scansione completa. La scansione percorre tutte le lingue attive, applica i tre analizzatori agli obiettivi attivati, persiste i problemi rilevati in ps_dfthincontent_issue, e marca come fixed i problemi che non vengono più rilevati (ad esempio se hai arricchito una scheda dall’ultima scansione).

Utilizzo — Lista dei problemi

Accessibile tramite Visualizza problemi nella barra degli strumenti. Visualizzazione paginata (50 per pagina) con filtri avanzati:

• Stato — aperto / corretto / ignorato.
• Tipo di problema — thin / duplicate / template.
• Tipo di oggetto — prodotto / categoria / CMS.
• Lingua — filtro su una delle lingue attive.
• Ricerca libera — sul nome dell’oggetto.

Ogni riga mostra la gravità (puntino rosso / arancione / blu), il tipo di problema, il tipo di oggetto con icona, il nome, la lingua, il numero di parole, la metrica rilevante (% similarità o % unicità) e tre pulsanti di azione:

• Suggerimento IA — apre un modale con un suggerimento di arricchimento HTML generato su richiesta (vedi sezione successiva).
• Marca come corretto — sposta il problema nello stato fixed. Rimane nello storico ma non inquina più i contatori.
• Ignora — sposta il problema nello stato ignored. Utile per pagine intenzionalmente brevi (ad esempio una pagina CMS “Contatti” legittimamente breve).

Esportazione CSV

Il pulsante Esporta CSV scarica tutti i problemi del filtro corrente. L’esportazione è in streaming in uscita (chunk di 500 righe) per gestire cataloghi grandi senza saturazione di memoria. Codifica UTF-8 con BOM per apertura diretta in Excel. Delimitatore punto e virgola.

Suggerimenti IA

Clicca sul pulsante IA su qualsiasi riga. Il modulo invia una richiesta all’endpoint configurato con un prompt costruito dinamicamente dal tipo di problema e dal tipo di oggetto:

• Thin prodotto — arricchire con USP, materiali, utilizzo, provenienza, garanzie.
• Thin categoria — arricchire con USP di gamma, consigli d’acquisto, confronto sottocategorie.
• Thin CMS — sviluppo editoriale, contestualizzazione, esempi.
• Duplicato — differenziare la scheda concentrandosi su ciò che la rende unica rispetto ai suoi duplicati.
• Template — rimuovere boilerplate, aggiungere elementi unici a questa pagina specifica.

Il messaggio di sistema impone un ritorno in HTML pulito: solo tag p, ul, li, h3. Niente markdown, niente tag radice. Puoi incollare il risultato direttamente nel campo descrizione di TinyMCE senza pulizia.

Il suggerimento viene memorizzato nel DB. Se riapri il modale più tardi, viene visualizzato all’istante senza una nuova chiamata API.

Cron — Scansioni pianificate

Il modulo espone un endpoint cron protetto da token, ideale per scansioni notturne:

https://tuo-negozio.com/modules/dfthincontent/cron.php?token=IL_TUO_TOKEN

Il token viene generato casualmente all’installazione e mostrato nel pannello di configurazione. Mantienilo riservato — dà accesso all’attivazione di una scansione completa.

Esempio crontab (scansione quotidiana alle 4)

0 4 * * * curl -s "https://tuo-negozio.com/modules/dfthincontent/cron.php?token=IL_TUO_TOKEN" > /dev/null 2>&1

Caratteristiche della scansione cron

• set_time_limit(0) — nessun limite di tempo PHP.
• memory_limit 512M — definito automaticamente.
• Ritorno JSON contenente il numero di oggetti analizzati, il numero di problemi rilevati e la durata totale.
• Validazione tramite hash_equals per resistere agli attacchi di timing.

Architettura tecnica

Struttura delle tabelle

• ps_dfthincontent_issue — un record per problema rilevato. Chiave unica: (id_object, object_type, id_lang, id_shop, issue_type). Campi notevoli: severity (1-3), word_count, content_hash (SHA1), metric_value (% similarità o unicità), metric_data (JSON con dettaglio), ai_suggestion, status, object_name, object_url.
• ps_dfthincontent_scan — storico delle scansioni. Data inizio / fine, durata, item analizzati per tipo, stato.

Hook utilizzati

• actionAdminControllerSetMedia — caricamento CSS / JS ed esposizione dell’URL AJAX tramite Media::addJsDef.
• actionProductUpdate — riscansione del prodotto modificato se auto-rescan attivato.
• actionObjectCategoryUpdateAfter — lo stesso per le categorie.
• actionObjectCmsUpdateAfter — lo stesso per le pagine CMS.

Limiti di prestazione

Il rilevamento di duplicati è intrinsecamente O(n²) — ogni pagina viene confrontata con tutte le altre pagine dello stesso tipo / lingua / negozio. Per evitare un’esplosione su cataloghi molto grandi, il modulo applica due protezioni:

• Tetto di sicurezza a 1 500 elementi per gruppo (tipo + lingua + negozio). Oltre, il rilevamento di duplicati è disattivato per quel gruppo — viene registrato un avvertimento.
• Pre-filtro per numero di parole — la similarità Jaccard viene calcolata solo tra item il cui numero di parole rientra in una finestra del ±50 %. Ciò elimina la grande maggioranza dei confronti inutili.

Risoluzione dei problemi

La scansione non parte

1. Apri la console di rete del browser, clicca su Avvia scansione completa, guarda la richiesta AJAX verso action=scanFull.
2. Se la risposta è HTML invece di JSON, è un fatal PHP lato server — controlla i log PrestaShop (var/logs/) e PHP.
3. Se la risposta è 404, verifica che il controller AdminDfThinContent sia correttamente registrato (tabella ps_tab).
4. Se la risposta è 403, il token CSRF è scaduto — ricarica la pagina e riprova.

I suggerimenti IA restituiscono un errore

• Verifica che la chiave API sia corretta e attiva presso il tuo provider.
• Verifica che il server possa raggiungere l’URL dell’endpoint (firewall in uscita, DNS).
• Se usi Ollama in locale, verifica che il servizio sia in esecuzione (ollama serve) e che il modello sia scaricato (ollama pull llama3.3).
• Consulta i log PrestaShop — il modulo registra lì gli errori cURL e i codici HTTP non-200.

Il cron restituisce 401 o 403

Il token trasmesso non corrisponde. Recupera il token corretto dal pannello di configurazione e sostituiscilo nel tuo crontab. Nessuno spazio, nessun ritorno a capo nel valore.

Vengono segnalati duplicati legittimi

È il caso tipico di varianti molto vicine (taglie dello stesso modello, colori). Tre opzioni:

• Marcare i problemi come ignorati uno per uno.
• Aumentare la soglia di similarità Jaccard al 95 % o più.
• Disattivare la scansione dei prodotti e mantenere solo categorie + CMS se il tuo caso d’uso non richiede la scansione prodotto.

Disinstallazione

Disinstalla tramite Moduli > Gestione moduli > Disinstalla. Il modulo rimuove pulitamente entrambe le tabelle DB, la scheda amministrativa e tutte le chiavi di configurazione. Nessuna traccia residua.

Risorse

• Pagina prodotto: datafirefly.com/it/product/dfthincontent/
• Supporto: support@datafirefly.com