Pickmapp

Widget lze jednoduše integrovat do webové stránky pouze vložením kódu. Následná konfigurace je možná přímo ve scriptu. Pro správné fungování a zobrazení na vašem webu je třeba:

Vložit HTML kód na stránku v místě, kde chcete zobrazit element s mapou výdejních míst
Vložit link na CSS styl
Vložit konfigurační script
Vložit link na hlavní javascript

Aktivace widgetu

PickMapp můžete do košíku svého webu implementovat kdykoliv. Aby se načetla výdejní místa, je potřeba aktivovat API klíč v uživatelském rozhraní PickMapp. Podrobněji je postup popsán na webu zde.

Testování widgetu

Pro testování widgetu lze využít zkušební období, které je zdarma do posledního dne v měsíci, v němž byla provedena aktivace vybraného tarifu. Více o tarifech najdete na webu.

HTML kód pro vložení widgetu na web:

 <div id="pbhmap" style="width: 99%; height: 600px;"></div>

Parametr width je povinný. Jeho hodnota může být libovolná.

Link na soubor CSS:

Do hlavičky svého webu vložte link na CSS. Pro správnou funkčnost využijte poslední dostupnou verzi CSS souboru:

poslední dostupná verze:

<link href="https://widget.postabezhranic.cz/template/assets/geowidget/v/1/1/styles.min.css" rel="stylesheet">

Vlastní CSS

Vzhled widgetu je možno přizpůsobit e-shopu, v němž bude integrován těmito způsoby

První možnost:

nahradit default CSS vlastním CSS, které si upravíte
CSS je možno zkopírovat z url a upravit: https://widget.postabezhranic.cz/template/assets/geowidget/styles.css
následně nahraďte link na v hlavičce za link na vlastní CSS styl
upozorňujeme, že v případě aktualizace default CSS, může dojít k přidání nebo úpravě elementů, které mohou způsobit, že se nebude widget zobrazovat správně

Druhá možnost (doporučujeme)

default CSS “přetížit” vlastním CSS
nalinkujte soubor s novými CSS styly pod základní styly

Javascript konfigurace

<script>
    let pbhParcelsMap = {
        'api_key': zadejtePickMappAPIklíč,
        'parcelshops': [{
                'number': 105,
                'filterName': 'Cargus',
                'filterColor': '#F68122',
            },
            {
                'number': 176,
                'filterName': 'FAN Courier',
                'filterColor': '#0F2346',
            },
            {
                'number': 177,
                'filterName': 'Slovenská pošta',
                'filterColor': '#003974',
            },
            {
                'number': 18,
                'filterName': 'Paczkomaty',
                'filterColor': '#FFCB04',
            },
        ],
        'translations': {
            "enter_location": "zadejte polohu",
            "monday": "pondělí:",
            "tuesday": "úterý:",
            "wednesday": "středa:",
            "thursday": "čtvrtek:",
            "friday": "pátek:",
            "saturday": "sobota:",
            "sunday": "neděle:",
            "navigate_to_location": "navigovat na výdejní místo",
            "pickup_here": "vyzvednu zde",
            "more_info": "více info"
        },
        'afterParcelshopSelectCallback': function(parcelshopNumber, courierNumber) {
            document.getElementById('parcelshop_id').value = parcelshopNumber;
            document.getElementById('courier_number').value = courierNumber;
        },
        'coutries': ['cz', 'sk', 'ro', 'pl'],
        'googleApiKey': 'zadejtevlastníGoogleAPIklíč',
        'defaultLlatitude': '50.0389467',
        'defaultLlongitude': '14.4292317'
    }; 
</script>

Parametry konfigurace javascriptu

'api_key': PickMapp API klíč (k získání v klientském rozhraní PickMapp)
'parcelshops': pole pro volbu dostupných přepravců (níže podrobněji popsané jednotlivé prvky pole), jednotlivé pole oddělujte čárkou
'translations': položky pro překlady textových částí a popisů widgetu
'afterParcelshopSelectCallback': JS event pro vrácení výstupních hodnot zvoleného výdejního místa
'coutries': definuje státy, které bude našeptávač nabízet (seznam kódů státu např. zde)
'googleApiKey': vlastní Google API klíč služby Place Autocomplete
'defaultLlatitude'/ 'defaultLlongitude': určení výchozích souřadnic mapy, pokud není poloha načtena geolokací z prohlížeče

Vložení odkazu na hlavní Javascript

Vložte poslední dostupnou verzi Javascriptu

<script src="https://widget.postabezhranic.cz/template/assets/geowidget/v/1/1/scripts.min.js"></script>

Konfigurační Javascript

Parametr 'parcelshops'

Ve widgetu PickMapp je možno zobrazit libovolné množství podporovaných přepravců. Uživatel může následně mezi jednotlivými přepravci filtrovat a zobrazit si pouze některé.

V rámci scriptu je třeba definovat u každého přepravce tyto parametry:

parametr number: Jedná se o číslo přepravce z číselníku Pošty bez hranic (shoduje se s číslem přepravce, které je využíváno v rámci API napojení Pošty bez hranic, není vázáno na služby Pošty bez hranic).
filterName: Jedná se o název přepravce. Je možné vyplnit libovolný název či zkratku, tak aby to bylo uživateli srozumitelné.
filterColor: Tímto parametrem nastavíte barevnost pole přepravce ve filtru. Zadávejte barvy ve formátu HEX. V seznamu podporovaných přepravců najdete doporučenou barvu, která vychází z logomanuálů přepravců.

Příklad:

'parcelshops': [
            {
                'number': 105,
                'filterName': 'CARGUS',
                'filterColor': '#F68122',
            },

Sloučení přepravců:

Widget nabízí možnost sloučit více přepravců do jednoho. Tuto možnost doporučujeme využít pokud:

chcete zobrazit přepravce po státech, což se hodí např. u eshopů, které nabízejí přepravu do více států na jedné doméně (např. .eu nebo .com)
chcete sloučit přepravce, kteří jsou rozdělení podle typu výdejního místa (parcelshop/locker a postoffice) z důvodů následného datového toku při odesílání zásilek (pro účely Pošty bez hranic).

Chcete-li zobrazovat více přepravce ve filtru jako jednoho přepravce, upravte hodnotu Number. Čísla sloučených přepravců oddělujte pomlčkou.

Příklad:

'parcelshops': [
            {
                'number': '192-191',
                'filterName': 'DHL',
                'filterColor': '#D50611,
            },

Seznam dostupných přepravců:

Stát - Číslo přepravce - Název přepravce - Barva pole přepravce

AT 11 Rakouská Pošta #FFDC00
BG 181 BOX NOW #45D62C
BG 108 eCont - parcelshop/locker #244183
BG 82 Speedy - parcelshop/locker #D20F37
CZ 105 Balíkovna #11A8E0
DE 192 DHL - postoffice #D50611
DE 191 DHL - parcelshop/locker #D50611
EE 134 Itella - parcelshop/locker #005EBF
FR 75 Colissimo #F68722
GR 178 BOX NOW #45D62C
HR 180 BOX NOW #45D62C
HR 187 Chorvatská Pošta - parcelshop/locker #FED431
HU 151 Maďarská pošta - postoffice #136C38
HU 150 Maďarská pošta - parcelshop/locker #136C38
LT 130 Itella - parcelshop/locker #005EBF
LV 132 Itella - parcelshop/locker #005EBF
PL 18 Paczkomaty #FFCB04
PL 152 Polská Pošta - parcelshop #E11221
RO 176 FAN Courier - parcelshop/locker #0F2346
SI 185 Slovinská Pošta - parcelshop/locker #FFDA56
SK 177 Slovenská Pošta - parcelshop/locker #003974
SK 142 Balíkovo #ED7E1D

parametr 'googleApiKey'

Aktivace Google API klíče

Pro správnou funkčnost vyhledávání v poli pro zadávání adresy je využívána služba Place Autocomplete, která vyžaduje Google API klíč.

Vygenerujte si vlastní API klíč, zkopírujte a vložte do kódu, návod na vygenerování API klíče: https://developers.google.com/maps/documentation/javascript/get-api-key

JS event: 'afterParcelshopSelectCallback'

Výstupní hodnoty

Widget po zvolení výdejního místa vrátí v metodě 'afterParcelshopSelectCallback' tyto proměnné:

ID výdejního místa (hodnota: parcelshop_id): Jedná se o číslo, kterým označuje Pošta bez hranic vybrané výdejní místo. Tuto hodnotu je následně potřeba datově přiřadit k zásilce, aby bylo možno zásilku doručit. (hodnota: id_lokality v API dokumentaci Pošty bez hranic)
číslo přepravce (hodnota: courier_number): Identifikuje, o kterého přepravce se jedná. Seznam přepravců je dostupný v sekci konfigurace.

Zde na stránce ukládáme pro ukázku hodnoty proměnných do inputů pod mapou a jsou vyplněny pomocí callbacku nastaveném v konfiguraci:

<input name="parcelshop" id="parcelshop_id">
<input name="courier_number" id="courier_number">

Konfigurace eventu odpovídající nastavení inputů:

        'afterParcelshopSelectCallback': function(parcelshopNumber, courierNumber) {
            document.getElementById('parcelshop_id').value = parcelshopNumber;
            document.getElementById('courier_number').value = courierNumber;
        },

Tento callback byste si měli definovat dle vašich potřeb. Například vyplnit si své skryté inputy v objednávkovém formuláři. V případě nemožnosti zásahu do html struktury eshopu, je možné pomocí callbacku plnit čísla do existujícího inputu, například ulice

(document.getElementById('street').value = parcelshopNumber + '-' + courierNumber;)

Zde záleží na možnostech e-shopu.

Integrace widgetu PickMapp

Před spuštěním widgetu

Implementace