1. Quick Start — integrace za 5 minut

Spolu s tímto dokumentem předáváme API klíč ve formátu ak_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx. API klíč propojuje widget s konfigurací na naší straně — výchozí jazyk, povolené země, povolené typy výdejních míst, vzhled apod.

Pro nasazení widgetu na stránce mapy výdejních míst není potřeba přístup do administrace widgetu — celé nastavení API klíče (režim, whitelist domén) je již provedeno z naší strany.

Poznámka: API klíč je vázaný na doménu www.ppl.cz (whitelist) a je v něm přednastaven režim inline (widget se vykreslí přímo do stránky, nikoliv jako modal okno). Žádné další úpravy klíče z Vaší strany nejsou potřeba.

1.1 Získání výchozího kódu z administrace widgetu

Nejrychlejší způsob, jak widget nasadit do e-shopu, je překopírovat hotový kód z administrace widgetu. V administraci je pro každý API klíč připraven výchozí HTML snippet, který obsahuje správný odkaz na loader a správně nakonfigurovaný element <ppl-access-point-widget> s vaším API klíčem. Tento kód stačí vložit na potřebné místo v aplikaci e-shopu (např. do šablony pokladny, do stránky s detailem objednávky apod.) a widget bude po načtení stránky automaticky inicializován.

V administraci widgetu přepněte na záložku Kód widgetu. Zobrazí se vygenerovaný HTML snippet připravený ke zkopírování — kliknutím na tlačítko Kopírovat se celý kód přenese do schránky:

Snippet se skládá ze dvou částí, které mají různé místo vložení ve stránce:

<script> tag s loaderem — patří ideálně do sekce <head> hostitelské stránky. Loader zajistí stažení všech potřebných assetů widgetu (JS, CSS, runtime konfiguraci) a registraci Custom Elementu <ppl-access-point-widget>. Skript lze umístit i na konec <body>, ale do <head> je umístění doporučené, aby byl widget připraven co nejdříve.

Element <ppl-access-point-widget> — patří přesně na to místo v DOM, kde má být widget zobrazen (typicky do šablony pokladny nebo do sekce pro výběr dopravy). Atribut api-key propojuje widget s konkrétním nastavením v administraci; atribut id umožňuje pohodlný přístup k elementu z JavaScriptu (document.getElementById("pplWidget")) — například pro naslouchání událostem nebo volání metody open() v modal režimu.

Kód vygenerovaný v administraci obsahuje reálný API klíč vázaný na vaši organizaci — tento klíč je nutné ponechat beze změny. V produkčním nasazení je zároveň vhodné držet API klíč v konfiguraci e-shopu (např. jako proměnnou šablony) a neukládat jej napevno do více míst v kódu.

Co lze v administraci nastavit ještě před zkopírováním kódu

Administrace widgetu umožňuje přednastavit výchozí chování widgetu na straně serveru tak, že samotný zkopírovaný HTML snippet zůstává minimální a na hostitelské stránce se už nic dalšího neupravuje. Po načtení widget provede API volání s api-key a z administrace si načte platnou konfiguraci. Mezi nejdůležitější volby patří:

Přidejte doménu whitelist — seznam domén, ze kterých smí být widget načítán. Slouží k zabezpečení API klíče proti zneužití na cizích stránkách. Do whitelistu zadávejte všechny domény, kde bude widget reálně zobrazován (produkční doména, staging, případně localhost pro vývoj).

Typ produktu — volba mezi Vlastní nastavení (explicitní seznam typů výdejních míst) a Smart 2 Box (automatický výběr typů podle logiky PPL). Typ produktu určuje, jaké výdejní body se ve widgetu nabídnou.

Typy výdejních míst — výběr konkrétních typů boxů a poboček, které mají být ve widgetu dostupné: AlzaBox, ParcelBox, ParcelShop. Toto nastavení se uplatňuje, pouze pokud je zvolen typ produktu Vlastní nastavení.

Režim zobrazení (viewMode) — výchozím režimem widgetu je modal (widget je skrytý a otevírá se po zavolání metody open()). V administraci lze režim přepnout na inline (widget se zobrazí přímo v page flow). Toto nastavení se do widgetu propíše automaticky podle api-key a v atributu config ho není třeba duplikovat. Pokud konkrétní stránka potřebuje jiný režim, než je nastaven v administraci, lze ho přepsat přes config (např. config='{"viewMode":"inline"}').

Další parametry z administrace — výchozí jazyk rozhraní, výchozí země, výchozí souřadnice mapy apod. Všechny tyto hodnoty se do widgetu propisují automaticky na základě api-key a není třeba je uvádět v atributu config na hostitelské stránce.

Poznámka: Dokud nejsou změny v administraci uloženy a aktivovány (tlačítko Aktivovat v horní části obrazovky), widget na hostitelské stránce používá poslední aktivovanou verzi konfigurace. Díky tomu lze změny bezpečně připravovat bez rizika, že se okamžitě projeví v produkci.

Kdy kód z administrace ručně upravit

Pokud vystačíte s výchozími hodnotami z administrace, kód není třeba upravovat vůbec. Úpravy snippetu z administrace dávají smysl typicky v těchto případech:

Chcete na konkrétní stránce přepsat některé výchozí nastavení (např. vynutit viewMode: "inline" na stránce, kde má být widget vložený přímo do rozložení, i když je v administraci nastaven modal). V takovém případě přidejte na element atribut config s JSON objektem — detaily viz kapitola 2.4.

Integrujete widget do React / Vue / Angular aplikace, kde je místo HTML zápisu potřeba použít framework-specific syntaxi (např. ref v Reactu pro přístup k DOM uzlu) — viz kapitoly 5 a 6.

Potřebujete widget otevírat programově (tlačítko "Vybrat výdejní místo"), naslouchat událostem (ppl-accesspointwidget-select, ppl-accesspointwidget-ready) nebo měnit konfiguraci za běhu.

Ve všech těchto případech zůstává výchozí kód z administrace základem — do snippetu pouze doplníte atributy (config, event listenery) nebo jej obalíte vhodnou komponentou frameworku. Zbytek nastavení nadále přichází z administrace podle api-key.

1.2 Minimální příklad (inline režim)

Widget se zobrazí přímo v page flow jako součást stránky. Výchozím režimem widgetu je modal — pro inline zobrazení je proto nutné mít v administraci widgetu (podle api-key) režim přepnutý na inline, nebo inline vynutit na element atributem config='{"viewMode":"inline"}'. Jazyk, země a další parametry se rovněž dědí z administrace, takže níže uvedený minimální příklad předpokládá, že administrace má režim nastavený na inline:

Poznámka: Atribut config používejte pouze v případě, že chcete některé výchozí nastavení z administrace pro konkrétní stránku přepsat — typicky pokud má administrace režim modal, ale konkrétní stránka potřebuje widget zobrazit inline (config='{"viewMode":"inline"}'). Detaily viz kapitola 2.4.

Widget je skrytý a zobrazí se jako fullscreen overlay po kliknutí na tlačítko. Modal je výchozí režim widgetu, takže pokud administrace režim nepřepsala na inline, atribut config není potřeba a stačí uvést pouze api-key. V příkladu níže je config='{"viewMode":"modal"}' uveden explicitně, aby příklad fungoval i v případě, kdy má administrace přepnuto na inline:

1.4 Co se děje při načtení widgetu

Sekvence načtení:

Prohlížeč stáhne loader skript z https://www.ppl.cz/accesspointwidget/loader.js

Loader načte configuration.js s runtime konfigurací (API URL, klíče)

Loader automaticky stáhne hashované JS a CSS soubory widgetu

Zaregistruje se Custom Element <ppl-access-point-widget>

Widget provede API volání na server PPL pro ověření api-key a získání konfigurace

Po úspěšné inicializaci se emituje událost ppl-accesspointwidget-ready

Widget je připraven k použití

1. Quick Start — integrace za 5 minut

1.1 Získání výchozího kódu z administrace widgetu#

Co lze v administraci nastavit ještě před zkopírováním kódu#

Kdy kód z administrace ručně upravit#

1.2 Minimální příklad (inline režim)#

1.3 Minimální příklad (modal režim)#

1.4 Co se děje při načtení widgetu#

1.1 Získání výchozího kódu z administrace widgetu

Co lze v administraci nastavit ještě před zkopírováním kódu

Kdy kód z administrace ručně upravit

1.2 Minimální příklad (inline režim)

1.3 Minimální příklad (modal režim)

1.4 Co se děje při načtení widgetu