Našeptáváč adres - Mapy.com / Google places

Našeptávač adres – zákazník napíše pár písmen, zbytek adresy se vyplní sám

Adresy dodává Mapy.cz (ideální pro ČR a Slovensko, zdarma) nebo Google Places (celý svět). Našeptává se v obchodě (registrace, Můj účet, pokladna) a volitelně i v administraci při ručním zadávání adres.

Proč tento modul

Adresní formulář je nejpracnější část objednávky – a zároveň místo, kde vzniká nejvíc chyb. Překlep v ulici, špatné číslo popisné nebo PSČ, které nepatří k městu, znamená zásilku, kterou dopravce nedoručí, a reklamaci, kterou řešíte vy. Na mobilu je ruční vypisování adresy navíc otravné natolik, že je to jeden z momentů, kdy zákazníci nákup vzdávají.

Našeptávač obojí řeší u zdroje: zákazník napíše tři písmena, vybere svou adresu ze seznamu skutečných existujících adres a všechna čtyři pole (ulice a číslo, město, PSČ, země) se vyplní sama – správně a najednou. Stejný komfort, jaký znáte z map na internetu nebo z pokladen velkých e-shopů.

Jak našeptávání funguje

• Našeptává se od nastaveného počtu znaků (výchozí 3) a seznam se průběžně zpřesňuje s každým dalším písmenem. Shodná část textu se v nabídce zvýrazňuje.
• Po výběru adresy se vyplní všechna pole najednou – ulice s číslem popisným, město, PSČ i země. Zákazník nic nepřepisuje, jen zkontroluje a pokračuje.
• PSČ se doplní ve formátu, který PrestaShop u dané země vyžaduje (např. „736 01“, ne „73601“) – formulář tedy projde validací na první pokus.
• Ovládání funguje i z klávesnice (šipky + Enter) a panel je přístupný pro čtečky obrazovky (ARIA).
• Našeptávač je jen pomocník navíc – zákazník může nabídku kdykoli ignorovat a adresu dopsat ručně. A pokud mapová služba zrovna neodpovídá, formulář funguje dál úplně normálně, jen bez nabídky.

Dva poskytovatelé adres: Mapy.cz a Google Places

Vyberete si, odkud se adresy berou – podle toho, kam prodáváte:

• Mapy.cz (doporučeno pro ČR a Slovensko) – nejlepší znalost českých a slovenských adres včetně čísel popisných. Registrace na developer.mapy.com je zdarma, bez platební karty, a bezplatný měsíční objem dotazů běžnému e-shopu s rezervou stačí. Pokud prodáváte hlavně v ČR/SK, není co řešit.
• Google Places – celosvětové pokrytí adres. Vyžaduje účet Google Cloud s platební kartou; Google poskytuje měsíční bezplatný objem a modul s dotazy aktivně šetří – všechny dotazy jedné rozepisované adresy spojuje do jedné účtované relace a výsledky si krátce pamatuje, takže se stejný dotaz neposílá dvakrát.

Přepnutí poskytovatele je otázkou dvou kliknutí v nastavení – vyberete službu, vložíte její API klíč, uložíte. Podrobný návod, jak klíč u obou služeb získat (krok za krokem, včetně odkazů), je přímo v nápovědě modulu.

Váš API klíč nikdy neopustí server

Modul je postaven jako serverová proxy: prohlížeč zákazníka se ptá vašeho e-shopu a teprve váš server se s API klíčem ptá mapové služby. Klíč se navíc posílá v HTTP hlavičce, ne v adrese požadavku. Nikdo ho tedy nemůže z webu opsat a spotřebovávat váš objem dotazů na cizím webu – na rozdíl od běžných řešení, která volají mapové API přímo z prohlížeče a klíč mají viditelný v kódu stránky.

Proti umělému protáčení dotazů (roboti, škodiči) je endpoint chráněn limitem požadavků na IP adresu za minutu (výchozích 60 běžného zákazníka nijak neomezí) a našeptávat se začíná až od nastaveného počtu znaků. Mapové službě se posílá pouze rozepsaný text adresy – nikdy žádné údaje o zákazníkovi, objednávce ani e-shopu.

Tři vzhledy panelu – ladí s každou šablonou

Vzhled nabídky adres vyberete v nastavení jedním kliknutím:

• Klasický – jednoduchý čistý seznam, který zapadne do každé šablony,
• Moderní – dvouřádkové položky s ikonou špendlíku (ulice tučně, město s PSČ pod ní) – vzhled známý z map,
• Tmavý – poloprůhledný panel pro e-shopy s tmavou šablonou.

Našeptává i v administraci

Dva samostatné vypínače určují, kde se našeptává: front office (registrace, Můj účet, pokladna) a administrace (Zákazníci → Adresy, adresy objednávek). Adresy zadávané ručně – třeba při objednávce po telefonu – tak vyplníte stejně rychle jako zákazník na webu, a se stejnou zárukou, že adresa skutečně existuje.

Nabízené země řídí váš e-shop, ne další nastavení

Modul si sám čte země aktivní ve vašem obchodě (Mezinárodní → Lokace → Země) – žádný další seznam neudržujete. V nastavení jen zvolíte režim:

• Podle země zvolené ve formuláři (doporučeno) – nabízejí se adresy ze země, kterou má zákazník ve formuláři právě vybranou; dokud země známá není, použijí se všechny aktivní země e-shopu,
• Vždy aktivní země e-shopu – nabízí se ze všech zemí, do kterých prodáváte, bez ohledu na výběr ve formuláři.

Nastavení za pět minut, vše na jedné záložce

Zapnout modul, vybrat poskytovatele, vložit API klíč – a našeptává se. Doladit pak můžete počet nabízených adres (výchozích 8), minimální délku dotazu, vzhled panelu, režim zemí, vypínače pro obchod a administraci i limit požadavků. Součástí administrace je podrobná česká nápověda ke každému nastavení včetně návodů na získání API klíčů.

Funguje se standardní šablonou hned – a s nestandardní taky

Adresní pole standardní šablony PrestaShopu si modul najde sám, bez jakéhokoli nastavování. Pro šablony a pokladny s nestandardními poli (typicky one-page checkouty) je připravena záložka Selektory: vlastní CSS selektory se k výchozím jen přidávají, takže nic nerozbijete, a v nápovědě je návod, jak selektor zjistit v prohlížeči krok za krokem. Modul zvládne i dvě adresy na jedné stránce (fakturační + dodací u OPC pokladen) – sám pohlídá, aby se ke každé adrese doplnilo její vlastní město, PSČ a země.

Technické parametry

• Kompatibilní s PrestaShop 1.7.x, 8.x i 9.x.
• Poskytovatelé adres: Mapy.cz (REST API Mapy.com) a Google Places API (New); přepínání v nastavení, jediné pole pro API klíč.
• API klíč uložen výhradně na serveru, veškerá komunikace se službami jde přes server e-shopu (proxy) a klíč se předává v HTTP hlavičce.
• Ochrana endpointu: limit požadavků na IP a minutu (nastavitelný), minimální délka dotazu, kontrola původu požadavku.
• Čistý JavaScript bez závislostí – žádné jQuery, žádné externí knihovny; do stránky se vkládá jen na stránkách s adresním formulářem.
• Šetří dotazy: prodleva při psaní, rušení překonaných požadavků, krátká mezipaměť odpovědí; u Googlu navíc účtovací relace spojující našeptávání a detail adresy do jednoho celku.
• Zvládá dynamicky překreslované formuláře (AJAX pokladna, změna země, modální okna v administraci) – pole si po překreslení znovu najde a rozepsanou práci neztratí.
• Nezasahuje do šablony ani do jádra PrestaShopu; při výpadku mapové služby zůstávají formuláře plně funkční.
• Podpora multistore – nastavení pro každý obchod zvlášť.

Každá vrácená zásilka kvůli chybné adrese stojí víc než tento modul. Nechte zákazníky adresu vybírat, ne vypisovat – rychleji objednají a vy doručíte napoprvé.