DataFirefly Address Lookup: dokumentacja

Prezentacja

DataFirefly Address Lookup dodaje autouzupełnianie adresu do formularzy PrestaShop 8 i 9: ścieżka zamówienia, strona „Mój adres”, strona „Moje dane” i formularz rejestracji. Moduł opiera się na dwóch silnikach: francuskim API BAN (api-adresse.data.gouv.fr), bezpłatnym i bez klucza, włączonym domyślnie dla Francji, oraz opcjonalnym Google Places dla adresów międzynarodowych.

Przepływ po stronie klienta jest prosty: wpisuje kod pocztowy, miasto uzupełnia się automatycznie (albo pojawia się selektor miejscowości, jeśli pasuje ich kilka); zaczyna wpisywać ulicę, pojawiają się podpowiedzi; jedno kliknięcie wypełnia naraz ulicę, kod pocztowy i miasto znormalizowanym adresem.

Wymagania

• PrestaShop 8.0 do 9.x (motyw Classic, Hummingbird albo większość motywów zewnętrznych)
• PHP 7.4 albo nowsze
• Wyłącznie dla Google Places: klucz API Google Cloud z włączonymi Places API i Maps JavaScript API

Instalacja

1. W back office PrestaShop otwórz Moduły → Menedżer modułów.
2. Kliknij Zainstaluj moduł i wskaż plik dfaddresslookup.zip.
3. PrestaShop instaluje moduł i automatycznie rejestruje hooki actionFrontControllerSetMedia oraz displayHeader.
4. Kliknij Konfiguruj, aby otworzyć ekran ustawień.

Od razu po instalacji autouzupełnianie działa dla Francji bez żadnej konfiguracji: API BAN jest włączone domyślnie i nie wymaga klucza. Dla adresów polskich trzeba dodatkowo włączyć Google Places.

Konfiguracja

Francuskie API BAN

Włącz francuskie API BAN: włącza albo wyłącza silnik francuski. Domyślnie włączony. API api-adresse.data.gouv.fr to bezpłatna usługa publiczna: bez klucza, bez abonamentu, z orientacyjnym limitem 50 zapytań na sekundę na adres IP, znacznie powyżej potrzeb checkoutu.

Uzupełniaj miasto na podstawie kodu pocztowego: gdy klient wpisze francuski pięciocyfrowy kod pocztowy, miasto uzupełnia się automatycznie, jeśli pasuje tylko jedna miejscowość; w przeciwnym razie pod polem pojawia się selektor miejscowości. Moduł nigdy nie nadpisuje miasta już wpisanego przez klienta.

Google Places (opcjonalnie)

Włącz Google Places: włącza silnik międzynarodowy. Wymaga poprawnego klucza API, w przeciwnym razie zapis konfiguracji zostanie odrzucony.

Klucz API Google: Twój klucz Google Cloud. Sposób jego utworzenia i zabezpieczenia opisano w kolejnej sekcji.

Dozwolone kraje: lista kodów ISO 3166-1 alfa-2 rozdzielonych przecinkami (na przykład PL,CZ,SK,DE). Google Places uruchamia się wyłącznie dla tych krajów; puste pole oznacza wszystkie kraje. To główna dźwignia kontroli rachunku w Google Cloud.

Zachowanie

Minimalna liczba znaków: liczba znaków przed uruchomieniem podpowiedzi (od 2 do 10, domyślnie 3).

Debounce (ms): opóźnienie między ostatnim naciśnięciem klawisza a wywołaniem API (od 80 do 2000 ms, domyślnie 250). Zwiększ, aby ograniczyć liczbę zapytań, zmniejsz, aby podpowiedzi były bardziej reaktywne.

Podświetlaj pasujące fragmenty: pogrubia w każdej podpowiedzi tekst wpisany przez klienta.

Uzyskanie klucza Google Places

1. Otwórz Google Cloud Console i wybierz albo utwórz projekt.
2. W APIs & Services → Biblioteka włącz Places API i Maps JavaScript API.
3. W APIs & Services → Dane logowania utwórz klucz API.
4. Ogranicz klucz: Ograniczenia aplikacji → „Odsyłacze HTTP” → dodaj swoją domenę (na przykład *.twoj-sklep.pl/*); Ograniczenia API → ogranicz do Places API i Maps JavaScript API.
5. Wklej klucz w konfiguracji modułu i zapisz.

Działanie techniczne

Automatyczne przełączanie silników

Moduł odczytuje kraj wybrany w polu id_country formularza. Francja to silnik BAN. Inny kraj obecny na liście dozwolonych krajów to Google Places. Kraj spoza listy albo brak zastosowania jakiegokolwiek silnika oznacza, że autouzupełnianie wyłącza się po cichu, a formularz pozostaje klasycznym formularzem do ręcznego wpisania. Przełączenie następuje natychmiast przy każdej zmianie kraju, bez przeładowania strony.

Zgodność z checkoutem jednostronicowym i przeładowaniami

Checkout PrestaShop ponownie renderuje formularz adresowy przy każdej zmianie kroku. Moduł obserwuje DOM przez MutationObserver i subskrybuje natywne zdarzenia updatedAddressForm, updatedAddress, updatedDeliveryForm oraz changedCheckoutStep: autouzupełnianie podłącza się ponownie automatycznie przy każdym przeładowaniu. Każdy formularz jest oznaczany po podłączeniu, aby uniknąć podwójnego podpięcia.

Kilka formularzy naraz

Jeśli wyświetlonych jest kilka formularzy adresowych jednocześnie (dostawa plus faktura), każdy otrzymuje własne, niezależne autouzupełnianie, z własną listą podpowiedzi i własnym stanem.

Obsługa klawiatury i dostępność

Listą podpowiedzi steruje się w całości z klawiatury: strzałki góra i dół do nawigacji, Enter do wyboru, Escape do zamknięcia. Podpowiedzi mają atrybuty ARIA role="listbox" i role="option".

Łagodna degradacja

Jeśli API jest nieosiągalne (awaria, klient offline, blokada sieciowa), żaden błąd nie jest wyświetlany: formularz pozostaje klasycznym formularzem do ręcznego wpisania. Autouzupełnianie to progresywne ulepszenie, nigdy punkt blokujący checkout.

RODO i prywatność

• Zapytania autouzupełniania idą bezpośrednio z przeglądarki klienta do API BAN (francuska usługa publiczna) albo do Google Places.
• Podczas wpisywania żadne dane nie przechodzą przez Twój serwer PrestaShop.
• Żadne dane nigdy nie przechodzą przez serwery DataFirefly.
• Moduł nie zakłada żadnych ciasteczek.
• Jeśli włączasz Google Places, wskaż Google w swojej polityce prywatności jako odbiorcę danych adresowych wpisywanych dla objętych krajów. Dla sklepu obsługującego rynek polski dotyczy to zdecydowanej większości zamówień.

Rozwiązywanie problemów

Podpowiedzi się nie pojawiają

• Sprawdź, czy właściwy silnik jest włączony w konfiguracji modułu.
• Sprawdź minimalną liczbę znaków: podpowiedzi uruchamiają się dopiero po przekroczeniu skonfigurowanego progu.
• Wyczyść cache PrestaShop (Parametry zaawansowane → Wydajność), aby wymusić ponowne załadowanie zasobów JS i CSS.
• Otwórz konsolę przeglądarki: błąd CORS albo blokada przez rozszerzenie (adblock, ochrona prywatności) może uniemożliwiać wywołania API.

Google Places się nie uruchamia

• Sprawdź, czy wybrany kraj znajduje się na liście dozwolonych krajów (albo czy lista jest pusta).
• Sprawdź w konsoli przeglądarki, czy skrypt Google Maps ładuje się bez błędu: nieprawidłowy klucz, niewłączone API albo zbyt restrykcyjne ograniczenie odsyłacza dają jednoznaczny błąd Google Maps JavaScript API error.
• Sprawdź, czy w Twoim projekcie Google Cloud włączono rozliczenia: API Places odrzuca zapytania bez aktywnego konta rozliczeniowego.

Miasto nie uzupełnia się na podstawie kodu pocztowego

• Ta funkcja dotyczy wyłącznie silnika BAN (Francja) i wyłącza się, jeśli pole miasta zawiera już wartość wpisaną przez klienta. Dla polskich kodów pocztowych uzupełnianie zapewnia Google Places przy podpowiedzi adresu.
• Niektóre kody pocztowe obejmują kilka miejscowości: moduł pokazuje wtedy selektor zamiast uzupełniać automatycznie.

Konflikt z zewnętrznym modułem checkoutu

Moduł celuje w pola po ich standardowych atrybutach name (address1, postcode, city, id_country). Zewnętrzne checkouty jednostronicowe, które zachowują te nazwy pól, działają bez konfiguracji. Jeśli zewnętrzny moduł zmienia nazwy pól, autouzupełnianie wyłącza się po cichu, nie psując checkoutu: skontaktuj się ze wsparciem, podając nazwę danego modułu.

FAQ

Czy moduł spowalnia mój sklep?

Nie. JS i CSS ładują się wyłącznie na 4 stronach zawierających formularz adresowy, a wszystkie zapytania autouzupełniania wykonuje przeglądarka klienta, nigdy Twój serwer.

Czy mogę korzystać wyłącznie z francuskiego API bez Google?

Tak, to tryb domyślny. Google Places jest ściśle opcjonalne i nie ładuje się, dopóki nie zostanie włączone z poprawnym kluczem. Dla adresów polskich pozostaje jednak niezbędne.

Czy moduł działa w trybie multistore?

Tak. Konfiguracja jest obsługiwana przez natywną tabelę konfiguracji PrestaShop i respektuje standardowy kontekst multistore.

Co się dzieje przy deinstalacji?

Wszystkie klucze konfiguracji są usuwane. Ponieważ żadna tabela nie została utworzona, deinstalacja nie zostawia śladów.

Changelog

1.0.0: 15 maja 2026

• Pierwsza wersja publiczna
• Francuskie API BAN zintegrowane domyślnie (bezpłatne, bez klucza)
• Opcjonalne Google Places z kluczem API i listą dozwolonych krajów
• Uzupełnianie kod pocztowy → miasto → ulica
• Zgodność z PrestaShop 8.0 do 9.x, checkoutem jednostronicowym i wieloetapowym
• Obsługa klawiatury, podświetlanie pasujących fragmentów, konfigurowalny debounce
• Zero nadpisań szablonów, zero tabel SQL