Nový mapový widget PPL 2.0

Spouštíme kompletně přepracovaný mapový widget pro výběr výdejních míst (PPL ParcelBoxy, AlzaBoxy a ParcelShopy). Pro vývojáře e-shopů to znamená tři věci: konec konfliktů s globálním CSS vašeho webu, integraci jedním HTML tagem bez závislosti na frameworku a svižnější běh v prohlížeči.

Migrační upozornění: Pokud na svém webu používáte upravenou (customizovanou) variantu původní verze 1.x, je potřeba nejpozději do 31. srpna 2026 přejít na verzi 2.0.

Kompletní technickou dokumentaci a referenci API najdete na oficiálním portálu dokumentace PPL Widget 2.0.

Architektonický posun: verze 1.x vs. Widget 2.0

Starší generace widgetu vkládala svůj kód do globálního prostoru stránky a vyžadovala ruční natažení externího CSS souboru do hlavičky dokumentu. Verze 2.0 mění princip integrace od základu.

1. Izolace pomocí Shadow DOM

Největší bolestí verze 1.x bylo přetékání stylů. Vývojáři museli úpravy řešit přes konkrétní selektory (např. #ppl-parcelshop-map .accordion-map--select { display: none !important; }) což podle použitého CSS frameworku (Tailwind, Bootstrap) často rozbíjelo vzhled e-shopu.

Widget 2.0 je postavený jako webová komponenta (Web Component) se Shadow DOM. Celý widget žije ve vlastním izolovaném DOM stromu:

➡️Globální styly vašeho e-shopu do widgetu nepronikají.

➡️Interní styly mapy naopak neovlivní vzhled vašeho košíku.

Důležité pro migraci: právě kvůli této izolaci přestávají fungovat staré CSS úpravy mířené na #ppl-parcelshop-map. Pokud jste si widget v1.x stylovali vlastním CSS, je to hlavní důvod, proč je nutná migrace. Vzhled a chování widgetu 2.0 se nastavuje přes konfiguraci v administraci API klíčů, ne přepisováním stylů zvenčí.

2. Povinná autorizace přes API klíč

V původní verzi stačilo na stránku vložit univerzální kontejner <div id="ppl-parcelshop-map">. Verze 2.0 zavádí správu přístupů přes API klíč.

Přínosy:

➡️vyšší bezpečnost a stabilita endpointů,

➡️konfigurace widgetu (povolené země, typy míst, jazyk) navázaná přímo na váš klíč,

➡️přehled o volání mapových služeb pro váš e-shop.

⚠️ Před integrací: Nejprve je nutné vygenerovat API klíč a aktivovat jej v administraci. Poté nezapomeňte nastavit povolenou doménu (nebo domény) v administraci widgetu — widget se načte pouze na doménách explicitně přiřazených k vašemu klíči.

3. Nezávislost na frameworku — React, Vue i čisté HTML

Konec krkolomných inicializací uvnitř životních cyklů komponent. Widget 2.0 je standardní webová komponenta a React má zabalený uvnitř — váš web tedy React (ani žádný jiný framework) mít nemusí.

Díky tomu funguje stejně jednoduše ve všech prostředích:

➡️Čisté HTML / Vanilla JS — vložíte jeden tag.

➡️React — vložíte stejný tag do JSX, na události reagujete běžným addEventListener.

➡️Vue, Angular a další — webové komponenty jsou nativně podporované všemi moderními frameworky.

Žádný zvláštní npm balíček ani serverový SDK nepotřebujete — integrace je vždy stejná: jeden HTML element.

Rychlý start: jak vypadá integrace v praxi

Načítání je asynchronní a neblokující — žádný synchronní <link rel="stylesheet"> v <head> jako dřív. Stačí natáhnout loader skript a vložit komponentu s API klíčem a konfigurací.

Statická HTML / Vanilla JS integrace

<!-- Loader si sám dohraje potřebné soubory widgetu -->

<script src="https://www.ppl.cz/accesspointwidget/loader.js" async></script>

<ppl-access-point-widget
    api-key="VÁŠ_API_KLÍČ"
></ppl-access-point-widget>

➡️api-key (povinné) — váš klíč přidělený PPL.

➡️config (volitelné) — JSON s nastavením: režim, jazyk, výchozí země, inline vs. modální zobrazení.

Zpracování výběru výdejního místa (Event Handling)

Widget oznamuje výběr přes vlastní událost (CustomEvent), kterou posílá přímo na svůj element (ne na document). Návratový objekt v event.detail je strukturovaný a typovaný — obsahuje přesná geolokační data, typ místa (ParcelShop / ParcelBox / AlzaBox) i informace o platbě.

JavaScript

<script>
const widget = document.querySelector("ppl-access-point-widget");

widget.addEventListener("ppl-accesspointwidget-select", (event) => {
  const selectedPoint = event.detail;
  console.log("ID zvoleného výdejního místa:", selectedPoint.id);
  console.log("Kompletní data:", selectedPoint);
});
</script>

Widget kromě výběru hlásí i další stavy, na které se dá navázat:

Událost	Kdy nastane
ppl-accesspointwidget-select	Uživatel vybral výdejní místo
ppl-accesspointwidget-close	Uživatel zavřel widget
ppl-accesspointwidget-error	Došlo k chybě (např. neplatný API klíč)
ppl-accesspointwidget-ready	Widget je inicializovaný a připravený

Nové funkce a vychytávky pro uživatele

Filtrování typů míst

Uživatel si během pár vteřin zúží výběr mezi PPL Boxy, partnerskými AlzaBoxy a kamennými PPL Shopy, a může filtrovat i podle dalších kritérií (otevírací doba, platba kartou, velikost zásilky, bezbariérovost). Filtry jsou optimalizované tak, aby i při změně více podmínek najednou proběhl jen jeden dotaz na server — výsledek se tak objeví rychle a bez zbytečné zátěže.

Oblíbená místa a historie přímo ve widgetu

Novinkou je ukládání oblíbených míst (ikonka srdíčka) a historie naposledy zvolených lokalit přímo v prohlížeči (Local Storage). Při opakovaném nákupu zákazník nemusí znovu vyhledávat — svá místa má hned po ruce.

Lepší chování na mobilu

Widget se přizpůsobuje velikosti prostoru, do kterého ho vložíte. Pokud nadřazený prvek nemá pevně danou výšku, widget se rozumně roztáhne tak, aby byl na mobilu v pokladně pohodlně použitelný — což pomáhá dokončení objednávky.

Vyhledávání a geolokace

Vyhledávání adresy s našeptávačem a možnost najít nejbližší místa podle aktuální polohy uživatele jsou samozřejmostí.

Harmonogram přechodu

➡️Widget v1.x (Legacy): architektonicky se dále nerozvíjí. Standardní integrace běží i nadále, ale silně customizované widgety (vlastní CSS úpravy, nestandardní e-commerce řešení) musí přejít na verzi 2.0.

➡️31. srpen 2026: konečný termín migrace všech customizovaných widgetů na verzi 2.0. Po tomto datu už nebudou staré CSS úpravy a integrace bez API klíče kompatibilní s novou sítí výdejních míst.

Kompletní referenční příručku — parametry, schéma návratových dat a interaktivní ukázky — najdete na oficiálním dokumentačním portálu PPL Widget 2.0