Hodnoty, které se vrátí po zvolení výdejního místa
(Zde jsou inputy zobrazeny pouze pro testovací účely)
ID výdejního místa
Číslo přepravce (PBH)

Pickmapp Pickmapp

Integrace widgetu 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:

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

Před spuštěním widgetu

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.

Verze PickMapp widgetu

v 1.1:

v 1.2:

v 1.3:

Implementace

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/3/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

Vložení odkazu na hlavní Javascript

Vložte poslední dostupnou verzi Javascriptu, script je nutné linkovat už před konfigurací.

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

Javascript konfigurace

Ukázka konfiguračního scriptu, jednotlivé prvky popsány podrobně níže.

let pickMappCgf = {

        'mapElementId': "pickMapp",
        'api_key': zadejtePickMappAPIklíč,
        'parcelshops': [{
                'number': 105,
                'filterName': 'Cargus',
                'filterColor': '#F68122',
                'active': 1, 
            },
            {
                'number': 176,
                'filterName': 'FAN Courier',
                'filterColor': '#0F2346',
                'active': 1,
            },
            {
                'number': 177,
                'filterName': 'Slovenská pošta',
                'filterColor': '#003974',
                'active': 1,
            },
            {
                'number': 18,
                'filterName': 'Paczkomaty',
                'filterColor': '#FFCB04',
                'active': 0,
            },
        ],
    '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 místo",
        "pickup_here": "vyzvednu zde",  
        "No_parcelshop_found_arround": "V okolí nenanlezeny žádné parcelshopy",
        "more_info": "více info"  
      },
  
        'coutries': ['cz', 'sk', 'ro', 'pl'],
        'googleApiKey': 'zadejtevlastníGoogleAPIklíč',
        'defaultLlatitude': '50.0389467',
        'defaultLlongitude': '14.4292317',
  
      'afterParcelshopSelectCallback': function (parcelshopNumber, courierNumber, name, address, city, zip, pIdCourier){
    console.log(parcelshopNumber);
    console.log(courierNumber);
    console.log(name);
    console.log(address);
    console.log(city);
    console.log(zip);
    console.log(pIdCourier); 
      },  
  };
  

pickmappInit(pickMappCgf);

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
  • pickmappInit : inicializace wigetu. Widget je možné inicializovat buď hned po načtení stránky (viz příklad výše) Popřípadě je možné inicializaci zavolat až je potřeba. Další výhoda je, že je možné kdykoliv přepsat konfiguraci a zavoláním pickmappInit se widget překreslí podle nové konfigurace

Podrobnější nápověda

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ů.
  • active: je nepovinný parametr, kterým můžeme jednoduchým způsobem ovlivnit jestli se výdejní místa daného přepravce po inicializaci zobrazí nebo ne. Pokud je použit u jednoho přepravce, je nutné ho definovat u všech. Pokud parametr použit není, je přepravce považován vždy za aktivního.

Příklad:

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

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,
                'active': 1, 
            },


Seznam dostupných přepravců:

Aktuální seznam implementovaných přepravců najdete v XLSX tabulce zde

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.
  • název výdejního místa (hodnota: name): název výdejního místa
  • adresa výdejního místa (hodnota: address): parametr definovaný přepravcem jako adresa, většinou se jedná o kombinaci ulice a čísla popisného. Někteří přepravci mají ale uvedenou v tomto parametru celou adresu včetně města a PSČ
  • město (hodnota: city): samostatně uvedené město ve kterém je zvolené výdejní místo
  • poštovní směrovací číslo (hodnota: zip): poštovní směrovací číslo zvoleného výdejního místa


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.

Reinicializace pomocí metody pickmappInit

Na začátku inicializujeme základní konfigurační soubor pomocí volání

pickmappInit(pickMappCgf);

potom třeba změnu nastavení widgetu

např:

pickMappCgf.parcelshops = [{"number":18,"filterName":"PACZKOMAT","filterColor":"FFCB04"}]
pickmappInit(pickMappCgf);

můžeme také provádět aktivace jen některých přepravců

to lze použitím syntaxe:

pickMappCgf.parcelshops[4].active = 1;
pickMappCgf.parcelshops[3].active = 1;
pickmappInit(pickMappCgf);