2. Vložení widgetu do stránky

2.1 Loader skript

Widget se načítá pomocí jediného loader skriptu, který automaticky stáhne aktuální verzi JS a CSS souborů:

Loader zajistí:

Načtení runtime konfigurace (configuration.js) s API URL a klíči

Stažení aktuální verze JS a CSS souborů (s cache-busting hashem)

Registraci Custom Elementu <ppl-access-point-widget>

Zabránění duplicitnímu načtení (pokud je skript vložen vícekrát)

Fallback UI při chybě načtení

Poznámka k URL: Atribut src u elementu <script> funguje s jakoukoli URL, která vrátí JavaScript obsah se správným Content-Type: application/javascript. URL nemusí končit příponou .js — prohlížeč se řídí hlavičkou odpovědi, ne příponou v URL.

Po načtení loaderu je element <ppl-access-point-widget> dostupný jako běžný HTML tag.

2.2 Požadavek na výšku kontejneru

Důležité: Widget interně používá :host { display: block; height: 100% } v Shadow DOM. Pro spolehlivé zobrazení v libovolném prostředí by měl mít jeho rodičovský element explicitně nastavenou výšku (v pixelech, viewport jednotkách nebo přes height chain až k elementu s pevnou výškou). V produkční integraci do e-shopu, kde je widget vnořen hluboko v DOM stromu spolu s hlavičkou, patičkou a dalšími sekcemi, je explicitní výška nezbytná — bez ní se widget zobrazí nesprávně nebo zkolabuje na minimální výšku.

Typická řešení — výběr dle kontextu:

a) Pevná výška v pixelech (doporučeno pro inline v page flow)

Nejběžnější a nejbezpečnější varianta — widget zabere konkrétní prostor uprostřed stránky:

Doporučená minimální výška je 500–600 px pro pohodlné zobrazení mapy a seznamu výdejních míst.

b) Roztažení na celou výšku viewportu

Pokud chcete, aby widget vyplnil celé okno (např. samostatná stránka s mapou), použijte viewport jednotky:

Pozor: Častý omyl: vložení widgetu přímo do <body> bez jakékoliv úpravy. Standardně má <body> auto-výšku odvozenou od obsahu, takže widget zkolabuje. Proto je nutné buď nastavit html, body { height: 100% } (height chain), nebo widget obalit do <div style="height: 100vh">. Pokud vám widget „zmizel" po vložení do stránky, zkontrolujte právě tohle.

c) Responzivní výška podle viewportu

Pro flexibilní chování (např. 80 % výšky okna) lze použít kombinaci viewport jednotek a minimální výšky:

Výjimka — modal režim: V modal režimu (viewMode: "modal") widget vytváří vlastní fullscreen overlay a nastavení výšky kontejneru není nutné. Widget si sám řídí rozměry overlay a kontejner v HTML zůstává prázdný s nulovou výškou.

2.3 Čekání na registraci elementu

Pokud potřebujete konfigurovat widget až po jeho registraci (např. při dynamickém načtení skriptu), můžete využít API prohlížeče:

Alternativně můžete využít událost ppl-accesspointwidget-ready, která se emituje po úspěšné inicializaci widgetu (viz kapitola 4.2).

2.4 Role atributu config a výchozí konfigurace z administrace

Widget si po načtení vyžádá výchozí konfiguraci ze serveru PPL (endpoint GET /v1/configuration). Tato konfigurace je navázaná na api-key a spravuje se v administraci widgetu — typicky obsahuje výchozí jazyk, zemi, povolené země, viewMode (inline/modal), povolené typy výdejních míst apod.

Výchozím režimem widgetu je modal. V administraci lze režim podle potřeby přepnout na inline. Nastavení z administrace se do widgetu propisuje automaticky podle api-key a v config ho není třeba duplikovat.

Atribut config slouží k přepsání (nebo zúžení) výchozí konfigurace z administrace — pro parametry, které se pro danou stránku nebo objednávku liší od globálního nastavení. Typickým případem je viewMode: pokud administrace má nastavený modal, ale konkrétní stránka potřebuje widget zobrazit inline (nebo naopak), lze to vynutit přes config='{"viewMode":"inline"}' resp. config='{"viewMode":"modal"}'. Obdobně se přes config předávají rozměry zásilky z aktuálního košíku, předvybrané místo, dynamická země zákazníka apod.

Jediný povinný atribut je api-key. Pokud atribut config neuvedete, widget použije výhradně výchozí konfiguraci z administrace.

Doporučený postup:

Nejprve nastavte preferované hodnoty (výchozí jazyk, země, viewMode, povolené typy AP…) v administraci widgetu pro váš api-key.

V HTML integrujte widget s jediným atributem api-key.

Atribut config používejte pouze tam, kde se konkrétní integrace musí lišit od globálního nastavení (typicky dynamická data z košíku nebo override pro konkrétní stránku).

Úplný seznam parametrů, které lze přes config přepsat, najdete v kapitole 7.5.

2.5 Formát atributu config — strict JSON

Atribut config vyžaduje validní JSON (ne JavaScript objekt). Při nevalidním JSON se config neparsuje a widget použije pouze serverovou konfiguraci. Chyba se zobrazí v browser console.

Nejčastější chyby:

Další časté chyby:

Single quotes — {'viewMode': 'modal'} — JSON vyžaduje dvojité uvozovky

Komentáře — // komentář nebo /* */ nejsou v JSON povoleny

2. Vložení widgetu do stránky

2.1 Loader skript#

2.2 Požadavek na výšku kontejneru#

a) Pevná výška v pixelech (doporučeno pro inline v page flow)#

b) Roztažení na celou výšku viewportu#

c) Responzivní výška podle viewportu#

2.3 Čekání na registraci elementu#

2.4 Role atributu config a výchozí konfigurace z administrace#

2.5 Formát atributu config — strict JSON#