# 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:…
- Strona:
- Język: pl
- Zaktualizowano: 2026-08-25
- Inne języki: [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), [de](https://www.datafirefly.com/de/documentation/dfaddresslookup/index.md), [it](https://www.datafirefly.com/it/documentation/dfaddresslookup/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfaddresslookup/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfaddresslookup/index.md)
- Indeks:
## 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 (data.geopf.fr/geocodage), 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.
**Sklepy działające w Polsce.** Silnik BAN obsługuje wyłącznie terytorium Francji. Dla adresów polskich podpowiedzi zapewnia Google Places, więc przy sprzedaży skierowanej na rynek polski to Google Places jest silnikiem podstawowym i wymaga klucza API. Silnik BAN pozostaje bezpłatnym dodatkiem dla klientów francuskich.
**Żadne dane nie przechodzą przez Twój serwer ani przez DataFirefly.** Zapytania idą bezpośrednio z przeglądarki klienta do API BAN albo Google Places. Moduł nie tworzy żadnej tabeli SQL i nie nadpisuje żadnego szablonu Smarty.
## 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 (New)_ 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 data.geopf.fr/geocodage 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](https://console.cloud.google.com/) i wybierz albo utwórz projekt.
2. W **APIs & Services → Biblioteka** włącz **Places API (New)** 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 (New) i Maps JavaScript API.
5. Wklej klucz w konfiguracji modułu i zapisz.
Nigdy nie wdrażaj klucza Google bez ograniczenia po odsyłaczu HTTP: mógłby go użyć dowolny obcy serwis, generując rachunek na Twój koszt.
## 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.1.0 — 23 sierpnia 2026
- Migracja silnika Google do Places API (New): programistyczne API AutocompleteSuggestion z tokenami sesji i Place.fetchFields; widget legacy jest niedostępny dla nowych klientów Google Cloud od marca 2025
- Podpowiedzi Google wyświetlają się na własnej liście modułu: ujednolicone UX, obsługa klawiatury, podświetlanie, ograniczenie do wybranego kraju
- Francja może być w całości obsługiwana przez Google Places po wyłączeniu silnika BAN
### 1.0.3 — 23 sierpnia 2026
- Poprawka: na niektórych motywach zewnętrzny skrypt przywracał wpisany tekst w polu ulicy po wybraniu podpowiedzi, pozostawiając adres niewypełniony; ulica jest teraz zapisywana jako ostatnia, a jej wartość ponownie ustawiana w razie nadpisania
- Ochrona przed ponownym otwarciem listy podpowiedzi opiera się teraz na oknie czasowym
### 1.0.2 — 23 sierpnia 2026
- Poprawka: lista podpowiedzi pozostawała otwarta po wybraniu adresu, ponieważ wyszukiwanie było ponownie uruchamiane przez syntetyczne zdarzenia emitowane podczas wypełniania pól
### 1.0.1 — 1 lipca 2026
- Migracja francuskiego silnika do usługi geokodowania Géoplateforme (data.geopf.fr/geocodage, IGN) po wyłączeniu starego endpointu api-adresse.data.gouv.fr pod koniec stycznia 2026
- API iso-funkcjonalne: te same parametry, ta sama odpowiedź GeoJSON, ten sam limit 50 zapytań na sekundę na IP
- Zaktualizowane etykiety back office i atrybucja podpowiedzi
### 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