DataFirefly Address Lookup — Documentazione
Installazione, impostazioni e risoluzione dei problemi dei suggerimenti di indirizzo: servizio gratuito della Géoplateforme (IGN, dati BAN) per la Francia e l'oltremare, Google Places API (New) facoltativo per gli altri paesi.
Presentazione
DataFirefly Address Lookup suggerisce indirizzi mentre il cliente digita nei moduli di indirizzo di PrestaShop: il checkout (clienti e ospiti, indirizzo di consegna e di fatturazione) e Il mio account > I miei indirizzi. Il cliente digita l’inizio dell’indirizzo, sceglie un suggerimento e il modulo compila via, CAP, città e, nei paesi che le hanno, la provincia o lo stato.
Sono disponibili due fornitori, scelti paese per paese:
- Géoplateforme: servizio di geocodifica dell’IGN (istituto geografico nazionale francese) basato sulla banca dati nazionale degli indirizzi (BAN),
data.geopf.fr/geocodage. Gratuito, senza chiave. Sostituisceapi-adresse.data.gouv.fr, dismessa a fine gennaio 2026. - Google Places API (New): facoltativo, con la tua chiave Google Maps Platform, per i paesi che la Géoplateforme non copre.
Novità della 2.0.0: fornitore per paese, territori d’oltremare serviti dalla Géoplateforme, Google caricato solo quando serve, provincia/stato compilato, elenco dei suggerimenti pienamente usabile da tastiera e con i lettori di schermo, pulsante «Inserisci il mio indirizzo manualmente», anteprima e test nel back office, nota sulla privacy, statistiche senza dati personali, 8 lingue, compatibilità estesa a PrestaShop 1.7.8.
Requisiti e compatibilità
- PrestaShop da 1.7.8 a 9.x, PHP 7.1 o superiore.
- Temi Classic e Hummingbird, e i temi che mantengono i nomi di campo standard (
address1,postcode,city,id_country,id_state). jQuery non necessario. - Moduli di checkout che mostrano il modulo di indirizzo standard, per esempio DataFirefly Simple Checkout.
- Solo per Google Places: una chiave Google Cloud con Places API (New) e Maps JavaScript API attivate e la fatturazione attiva.
Installazione e aggiornamento
- In Moduli > Gestione moduli, clicca su Carica un modulo e deposita
dfaddresslookup-2.0.0.zip. - Clicca su Configura. Senza altre impostazioni, la Francia e i territori d’oltremare ricevono i suggerimenti della Géoplateforme.
Aggiornamento dalla 1.0.x o dalla 1.1.0: carica il nuovo zip sopra il precedente. Tutte le impostazioni sono conservate; l’elenco «Paesi consentiti (Google)» della 1.x diventa la tabella dei fornitori per paese, così gli stessi paesi mantengono gli stessi suggerimenti. Lo script di aggiornamento svuota anche la cache CSS combinata di PrestaShop, che altrimenti continuerebbe a servire il vecchio foglio di stile.
Panoramica
La prima scheda riassume cosa vedono i clienti: numero di paesi per fornitore, pagine, nota sulla privacy, moduli di checkout rilevati e contatori degli ultimi 30 giorni.

Paesi e fornitori
Ogni paese attivo nel negozio ha la sua scelta: Automatico, Géoplateforme, Google Places o Nessun suggerimento. In automatico, la Géoplateforme serve i paesi in cui ha indirizzi; per gli altri, l’impostazione «Paesi non coperti dalla Géoplateforme» sceglie Google Places (se è impostata una chiave) o nessun suggerimento. La colonna Risultato si aggiorna in diretta.
La Géoplateforme copre la Francia metropolitana, Guadalupa, Martinica, Guyana francese, Riunione, Mayotte, Saint-Pierre e Miquelon, Saint-Barthélemy e Saint-Martin, e in parte la Nuova Caledonia e la Polinesia francese. Non ha dati per Wallis e Futuna né per Monaco. Anche un indirizzo d’oltremare digitato con il paese «Francia» viene trovato.

Impostazioni di ricerca
- Numero minimo di caratteri (da 2 a 10, 3 predefinito; la Géoplateforme ne richiede almeno 3).
- Attesa prima della ricerca (da 80 a 2000 ms, 250 predefinito): pausa dopo l’ultimo tasto.
- Numero di suggerimenti (da 1 a 10, 6 predefinito) e tempo massimo (da 1000 a 15000 ms) oltre il quale la ricerca viene abbandonata.
- Evidenzia il testo digitato, città dal CAP, pulsante Inserisci il mio indirizzo manualmente.
- Pagine: checkout e/o I miei indirizzi. Lo script viene caricato solo in queste pagine, e per niente se nessun paese ha un fornitore. Un campo avanzato accetta i controller di un modulo di checkout con una propria pagina.
- Colore di accento: vuoto, viene usato il colore principale del tema.

Chiave Google Places
Il modulo usa solo Places API (New): il vecchio widget Places Autocomplete non è più offerto ai nuovi progetti Google Cloud. Lo script di Google viene caricato solo quando un cliente digita un indirizzo in un paese servito da Google.
- Nella console Google Cloud, crea o scegli un progetto con la fatturazione attiva.
- In API e servizi, attiva Places API (New) e Maps JavaScript API.
- Crea una chiave API in Credenziali.
- Restrizioni delle applicazioni: Siti web. Aggiungi i referrer mostrati dal modulo (domini del negozio e del back office, pulsante Copia).
- Restrizioni API: limita la chiave a Places API (New) e Maps JavaScript API.
- Incolla la chiave, attiva Google Places, salva, poi clicca su Prova la chiave.
Fatturazione: il modulo raggruppa le ricerche di uno stesso indirizzo in un token di sessione, chiuso da un’unica richiesta Place Details limitata ai campi dell’indirizzo (categoria Essentials). Google fattura questo utilizzo sul tuo account secondo il listino in vigore; il numero di sessioni compare nella scheda Statistiche. Per impostazione predefinita vengono suggeriti solo indirizzi (numeri civici, edifici, vie), non negozi.
Una chiave Maps JavaScript è visibile nelle pagine del negozio: non distribuirla mai senza restrizione sui referrer HTTP.

Anteprima e test
La scheda Anteprima e test riproduce un modulo di indirizzo con le impostazioni correnti, anche prima di salvare. I pulsanti di test interrogano la Géoplateforme e Google Places dal tuo browser, come farebbe un cliente, e indicano il tempo di risposta o la causa di un errore (chiave rifiutata, rete, direttiva CSP).

Lato cliente
Suggerimenti e tastiera
I suggerimenti compaiono sotto il campo Indirizzo, sopra la pagina: il modulo non si sposta. Ogni riga mostra la via, poi CAP, città e regione. Le frecce su e giù scorrono l’elenco, Invio sceglie, Esc chiude senza cancellare il testo; il numero di suggerimenti viene annunciato ai lettori di schermo.


Compilazione del modulo
I campi vengono compilati solo quando il cliente sceglie un suggerimento e sono brevemente evidenziati. Il complemento indirizzo non viene mai sostituito, e la città dal CAP compila solo un campo vuoto. I moduli di consegna e di fatturazione funzionano in modo indipendente, e il fornitore segue il paese scelto, anche quando PrestaShop ricarica il modulo.

Città dal CAP
Per i paesi serviti dalla Géoplateforme, un CAP di 5 cifre compila la città quando corrisponde un solo comune, o mostra l’elenco dei comuni quando sono più di uno.

Nessun risultato, errore, inserimento manuale
Quando nessun indirizzo corrisponde, o quando il servizio è lento, saturo (risposta 429) o non disponibile, l’elenco lo indica e ricorda che l’inserimento manuale resta possibile. Il pulsante Inserisci il mio indirizzo manualmente (o il tasto Esc) chiude l’elenco; l’ordine non viene mai bloccato.

Google Places per gli altri paesi
Per un paese servito da Google, i suggerimenti provengono da Google Places e riportano la dicitura «Google Maps». Alla scelta, anche lo stato o la provincia vengono selezionati nell’elenco di PrestaShop quando il paese li prevede.

Smartphone e I miei indirizzi
Su smartphone le righe sono alte almeno 48 px e l’elenco resta nello schermo. Gli stessi suggerimenti sono disponibili quando un cliente aggiunge o modifica un indirizzo nel suo account.


Privacy
Il testo digitato nel campo Indirizzo parte dal browser del cliente verso il fornitore del paese: la Géoplateforme (data.geopf.fr, senza cookie) o Google (maps.googleapis.com, solo per i paesi serviti da Google e solo quando il cliente digita). Nulla passa da DataFirefly. Sotto il campo compare una nota, in ogni lingua, con il nome del fornitore ({provider}) e un link facoltativo a una pagina CMS. Questa nota informa il cliente; non sostituisce la tua analisi dei tuoi obblighi.

Statistiche
Il modulo conta, per giorno e per fornitore, le ricerche, gli indirizzi scelti, le ricerche senza risultato, gli errori e le sessioni Google. Non viene salvato alcun indirizzo, indirizzo IP o identificativo del cliente. Il conteggio può essere disattivato e azzerato.

Sicurezza e Content Security Policy
- I suggerimenti sono costruiti come testo: nessun dato del fornitore viene inserito come HTML.
- Il modulo non usa script inline né
evale non ha proxy lato server. - Se il tuo negozio invia un’intestazione CSP:
connect-src https://data.geopf.frper la Géoplateforme; per Google, le direttive della scheda Aiuto (il nonce della pagina viene passato allo script di Google quando esiste).
Risoluzione dei problemi
Non compare nessun suggerimento
- Verifica che il modulo sia attivo e che la pagina sia tra quelle scelte.
- In Paesi e fornitori, controlla la colonna Risultato del paese scelto nel modulo.
- Avvia il test della Géoplateforme in Anteprima e test: un errore indica di solito un blocco di rete o una direttiva
connect-src. - Dopo un aggiornamento manuale dei file, svuota la cache in Parametri avanzati > Prestazioni.
Google Places non risponde
- Il pulsante Prova la chiave indica se Google rifiuta la chiave: API non attivata, fatturazione non attiva o dominio assente dai referrer.
- Il dominio del back office deve essere tra i referrer per il test e l’anteprima.
Un modulo di checkout di terze parti
I checkout che mantengono i nomi di campo standard funzionano senza impostazioni. Se hanno una propria pagina, aggiungi il loro controller in Altri controller. Se rinominano i campi, l’inserimento resta manuale, senza errori.
FAQ
Serve una chiave per la Francia?
No. La Géoplateforme è gratuita e senza chiave. Google Places è facoltativo.
Lo script viene caricato in tutte le pagine?
No: solo nel checkout e nella pagina dell’indirizzo (secondo le impostazioni), e lo script di Google solo quando un cliente digita in un paese servito da Google.
Cosa succede alla disinstallazione?
Le impostazioni e la tabella delle statistiche vengono eliminate.
Changelog
2.0.0 — 8 novembre 2026
- Fornitore per paese (automatico, Géoplateforme, Google Places, nessuno); territori d’oltremare creati come paesi distinti serviti dalla Géoplateforme
- Google: script caricato su richiesta, solo indirizzi, token di sessione chiuso da una richiesta Essentials, provincia/stato compilato, attribuzione Google Maps, rilevamento di una chiave rifiutata
- Nuovo elenco dei suggerimenti: stati di caricamento, nessun risultato, errore e pausa, pulsante di inserimento manuale, pattern ARIA combobox completo, dimensioni mobile
- Richieste obsolete annullate, tempo massimo, cache, pausa sulle risposte 429
- Back office rifatto: anteprima, test di connessione, aiuto per la chiave, nota sulla privacy, statistiche; 8 lingue
- Compatibile con PrestaShop da 1.7.8 a 9; aggiornamento dalla 1.0.x e dalla 1.1.0 senza perdita di impostazioni
1.1.0 — 23 agosto 2026
- Motore Google migrato a Places API (New)
1.0.3 e 1.0.2 — 23 agosto 2026
- Via conservata dopo la selezione; l’elenco non si riapre più dopo la scelta
1.0.1 — 1 luglio 2026
- Passaggio alla Géoplateforme (data.geopf.fr/geocodage)
1.0.0 — 15 maggio 2026
- Prima versione pubblica