# DataFirefly Address Lookup — Dokumentation
> Überblick DataFirefly Address Lookup fügt den Formularen von PrestaShop 8 und 9 eine Adress-Autovervollständigung hinzu: Checkout, Seite „Meine Adresse", Seite „Meine Daten" und Registrierungsformular. Das Modul stützt sich auf zwei…
- Seite:
- Sprache: de
- Aktualisiert am: 2026-08-25
- Weitere Sprachen: [fr](https://www.datafirefly.com/documentation/dfaddresslookup/index.md), [en](https://www.datafirefly.com/en/documentation/dfaddresslookup/index.md), [es](https://www.datafirefly.com/es/documentation/dfaddresslookup/index.md), [it](https://www.datafirefly.com/it/documentation/dfaddresslookup/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfaddresslookup/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfaddresslookup/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfaddresslookup/index.md)
- Index:
## Überblick
DataFirefly Address Lookup fügt den Formularen von PrestaShop 8 und 9 eine Adress-Autovervollständigung hinzu: Checkout, Seite „Meine Adresse", Seite „Meine Daten" und Registrierungsformular. Das Modul stützt sich auf zwei Engines: die französische BAN-API (data.geopf.fr/geocodage), kostenlos und ohne Schlüssel, standardmäßig für Frankreich aktiviert, und optional Google Places für internationale Adressen.
Der Kunden-Workflow ist einfach: er tippt seine Postleitzahl, die Stadt wird automatisch ausgefüllt (oder eine Gemeindeauswahl erscheint, wenn mehrere übereinstimmen); er beginnt, seine Straße einzugeben, Vorschläge erscheinen; ein Klick füllt Straße, Postleitzahl und Stadt auf einmal mit einer normalisierten Adresse.
**Keine Daten laufen über Ihren Server oder über DataFirefly.** Anfragen gehen direkt vom Browser des Kunden zur BAN-API oder zu Google Places. Das Modul erstellt keine SQL-Tabelle und überschreibt kein Smarty-Template.
## Voraussetzungen
- PrestaShop 8.0 bis 9.x (Classic-Theme, Hummingbird oder die meisten Drittanbieter-Themes)
- PHP 7.4 oder höher
- Nur für Google Places: ein Google-Cloud-API-Schlüssel mit aktivierten APIs _Places API (New)_ und _Maps JavaScript API_
## Installation
1. Öffnen Sie im PrestaShop-Backoffice **Module → Modul-Manager**.
2. Klicken Sie auf **Modul hochladen** und legen Sie die Datei `dfaddresslookup.zip` ab.
3. PrestaShop installiert das Modul und registriert automatisch die Hooks `actionFrontControllerSetMedia` und `displayHeader`.
4. Klicken Sie auf **Konfigurieren**, um den Einstellungsbildschirm zu öffnen.
Direkt nach der Installation ist die Autovervollständigung für Frankreich ohne jede Konfiguration aktiv: die BAN-API ist standardmäßig aktiviert und benötigt keinen Schlüssel.
## Konfiguration
### Französische BAN-API
**Französische BAN-API aktivieren** — schaltet die französische Engine ein oder aus. Standardmäßig aktiviert. Die API data.geopf.fr/geocodage ist ein kostenloser öffentlicher Dienst: kein Schlüssel, kein Abonnement, Richtwertlimit von 50 Anfragen pro Sekunde und IP, weit über den Bedürfnissen eines Checkouts.
**Stadt aus Postleitzahl vorausfüllen** — wenn der Kunde eine 5-stellige französische Postleitzahl eingibt, wird die Stadt automatisch ausgefüllt, wenn eine einzige Gemeinde übereinstimmt; andernfalls erscheint eine Gemeindeauswahl unter dem Feld. Das Modul überschreibt niemals eine bereits vom Kunden eingegebene Stadt.
### Google Places (optional)
**Google Places aktivieren** — schaltet die internationale Engine ein. Erfordert einen gültigen API-Schlüssel; andernfalls wird das Speichern der Konfiguration abgelehnt.
**Google-API-Schlüssel** — Ihr Google-Cloud-Schlüssel. Siehe nächsten Abschnitt zum Erstellen und Absichern.
**Erlaubte Länder** — durch Kommas getrennte ISO-3166-1-Alpha-2-Codes (z. B. `BE,CH,LU,DE`). Google Places wird nur für diese Länder ausgelöst; leeres Feld = alle Länder. Dies ist der Haupthebel, um Ihre Google-Cloud-Abrechnung unter Kontrolle zu halten.
### Verhalten
**Mindestzeichen** — Anzahl der Zeichen, bevor Vorschläge ausgelöst werden (2 bis 10, Standard 3).
**Debounce (ms)** — Verzögerung zwischen dem letzten Tastendruck und dem API-Aufruf (80 bis 2000 ms, Standard 250). Erhöhen Sie den Wert, um die Anzahl der Anfragen zu reduzieren, verringern Sie ihn für reaktionsschnellere Vorschläge.
**Treffer hervorheben** — hebt den vom Kunden getippten Text in jedem Vorschlag fett hervor.
## Einen Google-Places-Schlüssel erhalten
1. Öffnen Sie die [Google Cloud Console](https://console.cloud.google.com/) und wählen oder erstellen Sie ein Projekt.
2. Aktivieren Sie unter **APIs & Dienste → Bibliothek** die **Places API (New)** und die **Maps JavaScript API**.
3. Erstellen Sie unter **APIs & Dienste → Anmeldedaten** einen **API-Schlüssel**.
4. Beschränken Sie den Schlüssel: _Anwendungseinschränkungen_ → „HTTP-Referrer" → fügen Sie Ihre Domain hinzu (z. B. `*.meinshop.de/*`); _API-Einschränkungen_ → beschränken auf Places API (New) und Maps JavaScript API.
5. Fügen Sie den Schlüssel in die Modulkonfiguration ein und speichern Sie.
Setzen Sie niemals einen Google-Schlüssel ohne HTTP-Referrer-Beschränkung ein: er könnte von jeder Drittanbieter-Website verwendet werden und Abrechnungen zu Ihren Lasten erzeugen.
## Technische Funktionsweise
### Automatischer Engine-Wechsel
Das Modul liest das im Feld `id_country` des Formulars ausgewählte Land. Frankreich → BAN-Engine. Anderes Land in der Allowlist → Google Places. Land außerhalb der Liste oder keine anwendbare Engine → die Autovervollständigung deaktiviert sich stillschweigend und das Formular bleibt ein klassisches Eingabeformular. Der Wechsel erfolgt sofort bei jedem Länderwechsel, ohne Neuladen der Seite.
### One-Page-Checkout-Kompatibilität und Neu-Renderings
Der PrestaShop-Checkout rendert das Adressformular bei jedem Schrittwechsel neu. Das Modul beobachtet das DOM mit einem `MutationObserver` und abonniert die nativen Events `updatedAddressForm`, `updatedAddress`, `updatedDeliveryForm` und `changedCheckoutStep`: die Autovervollständigung verbindet sich bei jedem Neu-Rendering automatisch neu. Jedes Formular wird nach der Verknüpfung markiert, um Doppelverknüpfungen zu vermeiden.
### Mehrere Formulare
Werden mehrere Adressformulare gleichzeitig angezeigt (Versand + Rechnung), erhält jedes seine eigene unabhängige Autovervollständigung mit eigenem Dropdown und eigenem Zustand.
### Tastatursteuerung und Barrierefreiheit
Das Vorschlags-Dropdown ist vollständig per Tastatur steuerbar: Pfeiltasten hoch/runter zum Navigieren, Enter zum Auswählen, Escape zum Schließen. Die Vorschläge tragen die ARIA-Attribute `role="listbox"` und `role="option"`.
### Elegante Degradierung
Ist die API nicht erreichbar (Ausfall, Kunde offline, Netzwerkblockade), wird kein Fehler angezeigt: das Formular bleibt ein klassisches manuelles Eingabeformular. Die Autovervollständigung ist eine progressive Verbesserung, niemals ein Blocker im Checkout.
## DSGVO und Datenschutz
- Autovervollständigungs-Anfragen gehen direkt vom Browser des Kunden zur BAN-API (französischer öffentlicher Dienst) oder zu Google Places.
- Keine Daten laufen während der Eingabe über Ihren PrestaShop-Server.
- Keine Daten laufen jemals über DataFirefly-Server.
- Das Modul setzt keinen Cookie.
- Wenn Sie Google Places aktivieren, erwähnen Sie Google in Ihrer Datenschutzerklärung als Empfänger der Adresseingaben für die betroffenen Länder.
## Fehlerbehebung
### Vorschläge erscheinen nicht
- Prüfen Sie, ob die betreffende Engine in der Modulkonfiguration aktiviert ist.
- Prüfen Sie die Mindestzeichen-Einstellung: Vorschläge werden erst ab dem konfigurierten Schwellenwert ausgelöst.
- Leeren Sie den PrestaShop-Cache (**Erweiterte Einstellungen → Leistung**), um das Neuladen der JS/CSS-Assets zu erzwingen.
- Öffnen Sie die Browser-Konsole: ein CORS-Fehler oder eine Blockierung durch eine Erweiterung (Adblocker, Datenschutz) kann API-Aufrufe verhindern.
### Google Places wird nicht ausgelöst
- Prüfen Sie, ob das ausgewählte Land in der Allowlist enthalten ist (oder ob die Liste leer ist).
- Prüfen Sie in der Browser-Konsole, ob das Google-Maps-Skript fehlerfrei lädt: ein ungültiger Schlüssel, eine nicht aktivierte API oder eine zu strenge Referrer-Beschränkung erzeugt einen expliziten `Google Maps JavaScript API error`.
- Prüfen Sie, ob die Abrechnung in Ihrem Google-Cloud-Projekt aktiviert ist: die Places-APIs lehnen Anfragen ohne aktives Abrechnungskonto ab.
### Die Stadt wird nicht aus der Postleitzahl ausgefüllt
- Diese Funktion betrifft nur die BAN-Engine (Frankreich) und deaktiviert sich, wenn das Stadtfeld bereits einen vom Kunden eingegebenen Wert enthält.
- Manche Postleitzahlen decken mehrere Gemeinden ab: das Modul zeigt dann eine Auswahl statt automatisch auszufüllen.
### Konflikt mit einem Drittanbieter-Checkout-Modul
Das Modul zielt auf die Felder über ihre Standard-`name`-Attribute (`address1`, `postcode`, `city`, `id_country`). Drittanbieter-One-Page-Checkouts, die diese Feldnamen beibehalten, funktionieren ohne Konfiguration. Benennt ein Drittanbieter-Modul die Felder um, deaktiviert sich die Autovervollständigung stillschweigend, ohne den Checkout zu beschädigen — kontaktieren Sie den Support mit dem Namen des betroffenen Moduls.
## FAQ
### Verlangsamt das Modul meinen Shop?
Nein. JS und CSS werden nur auf den 4 Seiten mit Adressformular geladen, und alle Autovervollständigungs-Anfragen werden vom Browser des Kunden ausgeführt, nie von Ihrem Server.
### Kann ich nur die französische API ohne Google verwenden?
Ja, das ist der Standardmodus. Google Places ist strikt optional und lädt erst, wenn es mit einem gültigen Schlüssel aktiviert wird.
### Funktioniert das Modul im Multi-Shop?
Ja. Die Konfiguration wird über die native PrestaShop-Konfigurationstabelle verwaltet und respektiert den Standard-Multi-Shop-Kontext.
### Was passiert bei der Deinstallation?
Alle Konfigurationsschlüssel werden gelöscht. Da keine Tabelle erstellt wurde, hinterlässt die Deinstallation keine Spuren.
## Changelog
### 1.1.0 — 23. August 2026
- Migration der Google-Engine auf Places API (New): programmatische AutocompleteSuggestion-API mit Session-Tokens und Place.fetchFields; das Legacy-Widget ist für neue Google-Cloud-Kunden seit März 2025 nicht mehr verfügbar
- Google-Vorschläge erscheinen im moduleigenen Menü: einheitliche UX, Tastatursteuerung, Hervorhebung, Beschränkung auf das gewählte Land
- Frankreich kann vollständig über Google Places bedient werden, indem die BAN-Engine deaktiviert wird
### 1.0.3 — 23. August 2026
- Behoben: bei manchen Themes stellte ein Drittanbieter-Skript nach Auswahl eines Vorschlags den getippten Text im Straßenfeld wieder her, sodass die Adresse leer blieb; die Straße wird nun zuletzt geschrieben und ihr Wert bei Überschreibung erneut gesetzt
- Der Schutz gegen das Wiederöffnen des Vorschlagsmenüs nutzt jetzt ein Zeitfenster
### 1.0.2 — 23. August 2026
- Behoben: das Vorschlagsmenü blieb nach Auswahl einer Adresse geöffnet, da die Suche durch die beim Befüllen der Felder ausgelösten synthetischen Events erneut gestartet wurde
### 1.0.1 — 1. Juli 2026
- Migration der französischen Engine auf den Géoplateforme-Geokodierungsdienst (data.geopf.fr/geocodage, IGN), da der alte Endpoint api-adresse.data.gouv.fr Ende Januar 2026 abgeschaltet wurde
- Iso-funktionale API: gleiche Parameter, gleiche GeoJSON-Antwort, gleiches Limit von 50 Anfragen pro Sekunde und IP
- Backoffice-Beschriftungen und Vorschlags-Attribution aktualisiert
### 1.0.0 — 15. Mai 2026
- Erste öffentliche Version
- Französische BAN-API standardmäßig integriert (kostenlos, ohne Schlüssel)
- Optionales Google Places mit API-Schlüssel und Länder-Allowlist
- Vorausfüllen Postleitzahl → Stadt → Straße
- Kompatibel mit PrestaShop 8.0 bis 9.x, One-Page- und Mehrschritt-Checkout
- Tastatursteuerung, Treffer-Hervorhebung, konfigurierbares Debounce
- Keine Template-Überschreibung, keine SQL-Tabellen