DataFirefly Indexing API — Documentazione

Panoramica

DataFirefly Indexing API invia automaticamente i prodotti, le categorie e le pagine CMS del tuo negozio PrestaShop ai due canali di invio diretto esistenti: IndexNow tramite il relay api.indexnow.org, che propaga a Bing, Yandex, Naver e Seznam in una sola chiamata, e Google Indexing API (autenticazione Service Account OAuth2, firma JWT RS256 nativa). Il modulo si aggancia agli hook nativi PrestaShop, accoda ogni modifica in una coda con deduplica, e un CRON elabora il lotto ogni pochi minuti. Mantieni un registro completo degli invii e una dashboard del tasso di accettazione.

Requisiti

• PrestaShop 8.0 a 8.99, o PrestaShop 9.x
• PHP 7.4 a 8.3
• Estensioni PHP openssl (per la firma JWT RS256 di Google) e curl (per le richieste HTTP)
• Un CRON di sistema o un servizio CRON esterno per chiamare l’elaborazione della coda ogni 5 a 15 minuti
• Opzionale, per Google: un account Google Cloud con un progetto dove attivare l’Indexing API e creare un Service Account, e una proprietà Search Console verificata per il tuo dominio

Installazione

Passo 1: download

Scarica il ZIP dfindexingapi-1.0.0.zip dal tuo account DataFirefly dopo l’acquisto.

Passo 2: installazione dal back-office

1. Connettiti al tuo back-office PrestaShop
2. Vai a Moduli › Gestore moduli › Carica un modulo
3. Clicca su Seleziona file e scegli il ZIP scaricato
4. Convalida. PrestaShop decomprime e installa il modulo
5. Una volta installato, clicca su Configura

Passo 3: verifiche post-installazione

All’installazione, il modulo crea automaticamente:

• Le due tabelle SQL ps_df_indexapi_queue (coda) e ps_df_indexapi_log (registro)
• Una chiave IndexNow alfanumerica di 32 caratteri
• Un token CRON casuale di 32 caratteri
• 5 tab nel menu admin: padre DataFirefly Indexing API, poi Dashboard, Coda, Registro, Configurazione

Apri la tab Configurazione per passare al passo successivo.

Configurazione di IndexNow

IndexNow è il canale da configurare per primo: senza Service Account, senza OAuth, senza quota e senza restrizioni sul tipo di pagina. Solo una chiave da pubblicare alla radice del tuo dominio.

Capire IndexNow

IndexNow è un protocollo aperto promosso da Microsoft Bing e Yandex nel 2021, al quale si sono uniti Naver e Seznam. Generi una chiave alfanumerica, la pubblichi alla radice del tuo dominio come file accessibile pubblicamente, e chiami api.indexnow.org con una lista di URL. Il server verifica la chiave leggendo il file sul tuo dominio, poi propaga gli URL ai motori partecipanti. Schede prodotto, categorie e pagine CMS rientrano nel suo perimetro normale.

Metodo 1: riscrittura .htaccess (consigliata)

È il metodo più semplice: il modulo serve esso stesso il contenuto del file chiave tramite un controller frontend, e una regola .htaccess alla radice del tuo negozio reindirizza la richiesta a quel controller.

1. Nella configurazione del modulo, apri la tab IndexNow
2. Spunta Attiva IndexNow
3. Verifica il campo Host, che deve corrispondere al dominio del tuo negozio senza il protocollo (ad esempio mio-negozio.it)
4. Salva
5. Copia lo snippet .htaccess mostrato nella pagina di configurazione, generato dinamicamente con la tua chiave attuale
6. Incolla questo snippet in cima al file .htaccess alla radice di PrestaShop, subito dopo il blocco RewriteEngine on
7. Clicca su Testa IndexNow nella configurazione: il modulo chiama l’URL del file chiave sul tuo dominio e verifica che restituisca il contenuto previsto come text/plain

Metodo 2: file fisico

Se non puoi modificare il .htaccess, crea manualmente un file fisico alla radice del dominio.

1. Recupera la tua chiave IndexNow dalla configurazione del modulo (campo Chiave IndexNow)
2. Crea un file il cui nome sia esattamente la chiave + .txt (ad esempio a1b2c3d4e5f6.txt) alla radice del tuo dominio
3. Il contenuto del file deve essere solo la chiave stessa, senza interruzione di riga
4. Verifica che https://tuo-dominio.com/a1b2c3d4e5f6.txt restituisca la chiave come text/plain
5. Clicca su Testa IndexNow

Configurazione di Google Indexing API

L’API Google Indexing richiede un Service Account di Google Cloud. La procedura richiede circa 5 minuti.

Passo 1: creare un progetto Google Cloud

1. Vai a console.cloud.google.com e accedi
2. In alto, clicca sul selettore di progetto, poi Nuovo progetto
3. Dagli un nome (ad esempio Indexing API Negozio) e crealo
4. Seleziona il progetto appena creato

Passo 2: attivare l’Indexing API

1. Nel menu di sinistra, vai a APIs e servizi › Libreria
2. Cerca Indexing API
3. Clicca su Attiva

Passo 3: creare un Service Account

1. Vai a APIs e servizi › Credenziali
2. Clicca su Crea credenziali › Account di servizio
3. Dagli un nome (ad esempio indexing-api-prestashop)
4. Nessun ruolo IAM necessario: passa al passo successivo e finalizza la creazione
5. Nella lista degli account di servizio, clicca sull’account creato
6. Tab Chiavi › Aggiungi chiave › Crea nuova chiave
7. Formato JSON. Scarica e conserva il file, non potrà essere recuperato dopo

Passo 4: aggiungere il Service Account a Search Console

1. Copia l’email del Service Account (forma nome@progetto.iam.gserviceaccount.com) da Google Cloud
2. Vai a Google Search Console
3. Seleziona la tua proprietà (il dominio del tuo negozio)
4. Vai a Impostazioni › Utenti e autorizzazioni
5. Clicca su Aggiungi utente, incolla l’email del Service Account, seleziona il ruolo Proprietario
6. Convalida

Passo 5: incollare il JSON nel modulo

1. Apri il file JSON scaricato in un editor di testo
2. Copia tutto il suo contenuto
3. Nella configurazione del modulo, sezione Google Indexing API, spunta Attiva Google Indexing API
4. Incolla il JSON completo nel campo Service Account JSON
5. Salva

Passo 6: testare la connessione

Clicca sul pulsante Testa Google nella pagina di configurazione. Il modulo firma un JWT RS256, lo scambia contro un token OAuth2 e mostra il risultato. Se tutto è corretto, vedi un messaggio verde Autenticazione OK. Questo test valida l’autenticazione, non che Google terrà conto dei tuoi URL.

Configurazione del CRON

Il CRON è l’elemento che fa funzionare l’elaborazione della coda. Senza un CRON chiamato regolarmente, gli invii si accumulano ma non partono mai.

Azione process: elaborazione della coda

Da chiamare ogni 5 a 15 minuti. Il modulo elabora un lotto configurabile (predefinito 50 job) seguendo la deduplica e i filtri di indicizzazione, poi aggiorna il registro e la coda.

L’URL esatto è mostrato nella configurazione. Ha questo aspetto:

https://tuo-dominio.com/index.php?fc=module&module=dfindexingapi&controller=cron&dfaction=process&token=IL_TUO_TOKEN

Azione purge: pulizia del registro

Da chiamare una volta al giorno. Il modulo elimina i job e i log elaborati oltre la ritenzione configurata (predefinito 30 giorni).

https://tuo-dominio.com/index.php?fc=module&module=dfindexingapi&controller=cron&dfaction=purge&token=IL_TUO_TOKEN

Azione key: file chiave IndexNow

Utilizzata solo dalla riscrittura .htaccess. Non chiami mai questo URL manualmente.

Configurare il tuo CRON di sistema

Su Linux/cPanel, aggiungi due righe in crontab:

# Ogni 10 minuti: elaborazione della coda
*/10 * * * * curl -s "https://tuo-dominio.com/index.php?fc=module&module=dfindexingapi&controller=cron&dfaction=process&token=IL_TUO_TOKEN" > /dev/null

# Una volta al giorno alle 3: purge del registro
0 3 * * * curl -s "https://tuo-dominio.com/index.php?fc=module&module=dfindexingapi&controller=cron&dfaction=purge&token=IL_TUO_TOKEN" > /dev/null

Sicurezza del token CRON

Il token è un segreto di 32 caratteri generato all’installazione. Senza il token corretto nel parametro token=, il controller restituisce HTTP 403. Puoi rigenerare il token in qualsiasi momento dalla configurazione (pulsante Rigenera token CRON), ricordando poi di aggiornare le tue righe crontab con il nuovo token.

La Dashboard

La tab Dashboard è la tua vista d’insieme in tempo reale. Misura la salute tecnica delle chiamate API, non l’indicizzazione effettiva delle tue pagine.

Contatori della coda

Cinque card in cima alla pagina:

• In attesa: job creati ma non ancora elaborati
• In elaborazione: job bloccati in elaborazione da un CRON attivo
• Inviato: job elaborati con successo (cumulo storico non purgato)
• Errore: job che hanno fallito dopo N tentativi massimi
• Saltato: job creati ma ignorati da un filtro (ad esempio URL_DELETED per IndexNow)

Diagnostica dei provider

Due card mostrano lo stato di configurazione:

• Google Indexing API: attivo, mal configurato, o disattivato. Indica se il JSON Service Account è presente e valido
• IndexNow: attivo, mal configurato, o disattivato. Indica se la chiave e l’host sono configurati

Tasso di accettazione a 30 giorni

Tabella incrociata provider × stato sugli ultimi 30 giorni, con colorazione semantica: verde sopra il 90%, arancione tra 60 e 90%, rosso sotto. Se Google scende sotto il 90%, di solito è segno che hai superato la quota o che gli URL non sono più accessibili. Un tasso di accettazione del 100% significa che le tue notifiche sono state ricevute, non che gli URL siano stati indicizzati.

Grafico degli invii quotidiani

Grafico Chart.js che sovrappone due curve giornaliere: totale inviato e totale accettato. Utile per individuare rapidamente cali o picchi anomali.

La Coda

La tab Coda elenca tutti i job (pending, processing, submitted, error, skipped) con filtri nativi PrestaShop per negozio, tipo di oggetto, ID, provider, stato, data.

Stati dei job

• pending: creato, in attesa di elaborazione dal prossimo CRON
• processing: bloccato da un CRON attivo (transizione logica per evitare doppia elaborazione in parallelo)
• submitted: invio riuscito all’API. Il contatore di tentativi è congelato
• error: tutti i tentativi hanno fallito. Rimane visibile con il messaggio di errore esatto restituito dall’API
• skipped: creato e poi ignorato (ad esempio URL_DELETED IndexNow, o filtro disattivato)

Azioni per riga

Ogni riga offre:

• Rilancia: riporta il job in pending e azzera il contatore di tentativi
• Elimina: cancella il job dalla coda

Azioni in blocco

Pulsanti in cima alla lista:

• Rilancia tutti i job in errore: riporta in pending tutti i job in stato errore
• Purga job elaborati: elimina tutti gli submitted/skipped indipendentemente dall’età

Il Registro

La tab Registro elenca ogni invio individuale effettuato: provider, tipo, ID di oggetto, URL inviato, azione (URL_UPDATED o URL_DELETED), codice HTTP restituito, indicatore accettato/rifiutato, messaggio completo di risposta e data. Filtrabile, ordinabile, esportabile come CSV tramite l’HelperList standard di PrestaShop.

Filtri di indicizzazione

Nella configurazione, puoi attivare o disattivare indipendentemente tre tipi di oggetti:

• Prodotti: invio su creazione, modifica, eliminazione, disattivazione
• Categorie: invio su creazione, modifica, eliminazione. La radice di categoria (ID 1 e 2) è ignorata per sicurezza
• Pagine CMS: invio su creazione, modifica, eliminazione

Disattivare un filtro ferma immediatamente l’accodamento per quel tipo, ma non purga la coda esistente. Su un catalogo grande, restringere i filtri lato Google è il riflesso giusto per non esaurire la quota di 200 URL al giorno.

Multi-negozio

Il modulo è nativamente multi-negozio. La configurazione (chiavi Google, chiave IndexNow, host, attivazioni) è indipendente per sub-negozio. I job e i log sono delimitati per id_shop: lo stesso prodotto in due sub-negozi genera due job distinti con i propri URL canonici.

Per configurare indipendentemente ogni sub-negozio, usa il selettore multistore in cima all’admin prima di aprire la configurazione.

Hook PrestaShop ascoltati

Il modulo registra i seguenti hook all’installazione:

• actionProductSave: creazione o modifica di un prodotto. Se attivo, accoda URL_UPDATED; altrimenti URL_DELETED
• actionProductDelete: eliminazione definitiva di un prodotto. Accoda URL_DELETED
• actionObjectCmsAddAfter: creazione di pagina CMS
• actionObjectCmsUpdateAfter: modifica di pagina CMS
• actionObjectCmsDeleteAfter: eliminazione di pagina CMS
• actionCategoryAdd: creazione di categoria
• actionCategoryUpdate: modifica di categoria
• actionCategoryDelete: eliminazione di categoria
• displayBackOfficeHeader: iniezione di frammento CSS per lo stile della dashboard

Ogni hook costruisce l’URL canonico tramite l’oggetto Link ufficiale di PrestaShop, il che rispetta le tue preferenze SEO friendly URL e i prefissi di lingua multilingua.

Risoluzione dei problemi

Il test Google fallisce con codice 401

L’autenticazione è fallita. Verifica che:

• Il JSON Service Account incollato sia completo e ben formato
• L’Indexing API sia ben attivata in Google Cloud (libreria)
• L’orologio del sistema del server sia corretto: uno scostamento di più di 5 minuti invalida il JWT

Il test Google fallisce con codice 403

L’autenticazione riesce ma Google rifiuta la richiesta. Causa abituale: il Service Account non è stato aggiunto come Proprietario della proprietà Search Console. Riverifica il passo 4 della configurazione Google.

Il test IndexNow fallisce

Il server api.indexnow.org non è riuscito a leggere il file chiave sul tuo dominio. Possibili cause:

• Lo snippet .htaccess non è stato incollato, o incollato nel posto sbagliato (deve essere dopo RewriteEngine on)
• Il file fisico non è stato creato, o non ha il nome corretto (deve essere esattamente la chiave + .txt)
• Il contenuto del file non corrisponde alla chiave (errore di battitura, interruzione di riga aggiuntiva)
• Il server web serve il file con il Content-Type sbagliato (deve essere text/plain)
• Il firewall o il CDN blocca le richieste del robot IndexNow

Apri https://tuo-dominio.com/LA_TUA_CHIAVE.txt in un browser in navigazione privata: devi vedere solo la chiave come testo semplice.

Job bloccati nello stato processing

Significa che un CRON ha bloccato i job ma non ha mai rilasciato il lock (ad esempio il processo è stato terminato da un timeout PHP). Puoi sbloccarli manualmente tramite phpMyAdmin:

UPDATE ps_df_indexapi_queue SET status = 'pending', attempts = 0 WHERE status = 'processing';

Se il problema si ripete regolarmente, aumenta il max_execution_time PHP del tuo hosting, o riduci la dimensione del lotto nella configurazione del modulo.

Quota Google superata

Google risponde con codice 429 o messaggio Quota exceeded. La quota predefinita è di 200 URL al giorno per Service Account.

Tre opzioni realistiche:

• Aspettare 24h, dato che la quota si reimposta giornalmente
• Restringere i filtri di indicizzazione lato Google ai tipi che contano davvero per te (ad esempio solo prodotti, disattivando categorie e CMS)
• Creare un secondo Service Account e alternare, avendo ogni Service Account la propria quota di 200 URL al giorno

Promemoria: IndexNow non ha quota. Se il volume è il tuo vincolo principale, è il canale su cui appoggiarsi.

Reinizializzazione completa

Per ripartire da zero (utile in caso di migrazione o problema complesso):

1. Disinstallare il modulo da Moduli › Gestore
2. Reinstallare: le tabelle vengono ricreate, la chiave IndexNow e il token CRON vengono rigenerati
3. Riconfigurare Google e IndexNow
4. Aggiornare lo snippet .htaccess con la nuova chiave
5. Aggiornare le righe crontab con il nuovo token

Limitazioni note

• Google Indexing API ufficialmente limitata alle pagine JobPosting oppure BroadcastEvent dentro un VideoObject. L’API accetta altri tipi e risponde 200, ma quel codice attesta solo la ricezione della notifica. Per un catalogo prodotti, IndexNow è il canale principale e Google un complemento registrato
• Quota Google limitata a 200 URL al giorno per Service Account, senza aumento realistico disponibile per un e-commerce (vedi Risoluzione dei problemi)
• IndexNow non gestisce URL_DELETED: il protocollo considera un 404 o 410 sull’URL come il modo corretto di segnalare un’eliminazione. Il modulo ignora quindi i job IndexNow in URL_DELETED (Google li invia correttamente)
• Varianti di prodotti non inviate individualmente: l’URL canonico del prodotto principale basta, Google consolida le varianti naturalmente
• Radice di categoria ignorata (ID 1 e 2) per evitare di inviare URL non pertinenti
• Il modulo non sostituisce una sitemap XML: la sitemap resta il canale di scoperta ufficiale e deve restare pulita e aggiornata. L’invio diretto si aggiunge sopra, non la rimpiazza

Supporto

Per qualsiasi domanda tecnica: support@datafirefly.com, risposta entro 24h lavorative in italiano, inglese o francese. Incluso per 12 mesi dopo l’acquisto.