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 Engines: die französische BAN-API (api-adresse.data.gouv.fr), 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.

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 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 api-adresse.data.gouv.fr 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 und wählen oder erstellen Sie ein Projekt.
2. Aktivieren Sie unter APIs & Dienste → Bibliothek die Places API 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 und Maps JavaScript API.
5. Fügen Sie den Schlüssel in die Modulkonfiguration ein und speichern Sie.

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.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