HD Standard implementation manual

This document contains information regarding standard implementation of Packeta Home Delivery (HD) address selection using an embeddable application. Please embed the application using the integration library described bellow.

HD Supported browser versions

List of minimal supported browser versions:

  • Google Chrome 79
  • Mozilla Firefox 79
  • Microsoft Edge 18
  • Safari 11
  • Opera 70

HD Intended audience

This manual is intended for technically advanced internet stores which require and are able to implement custom interaction with an embeddable application.

Specifically, the following skills are required:

  • basic JavaScript programming
  • basic HTML/CSS knowledge

HD Quick start - examples

We provide an integration library that will help you with the embedding of the widget to your website, which you may mirror (without automatic updating) and/or use in any way:

  • library.js
  • example using the library: simple, complex, combination
  • please note you have to provide your API key (search for packetaApiKey) for the examples to work
    • API key is an identifier of your Packeta account, available in Packeta client section, or can be provided by your account manager

HD Basic embeddable application implementation details

The embeddable application lives in an isolated iframe, which cannot interact with your main webpage in any other way than sending messages using window.postMessage().

The embedable application will use the parameters of the pick function mentioned bellow as query string parameters of the iframe. e.g. https://hd.widget.packeta.com/v6/#/?layout=hd&carrierId=80&apiKey=c65a2d0ee3cb844f&country=cz,sk (this is just example - use your own ApiKey for the correct functioning of the widget, allowed countries, etc.)

Iframe permissions:

  • recommended: sandbox="allow-scripts allow-same-origin" allow="geolocation"
  • minimal required: sandbox="allow-scripts"
  • please note that geolocation is only available if your internet store is served over https (not just http)
  • cookies persistence

There are two distinct possible modes of operation in the shopping cart:

  1. the pick-up point selection is done in a modal dialog (which opens after the customer selects delivery to Packeta pick-up point, or by a button available next to such delivery method)
  2. inline UI controls, part of delivery method selection Both modes are supported by the application. When doing the later, make sure to test on mobile phones and tablets.

HD Integration library - methods

We provide an integration library available at this URL:

The library provides following methods:

Packeta.Widget.pick(apiKey, callback, options, inElement)

This method launches the widget. There is no return value.

Argument Type Required Description
apiKey|string[16] yes An identifier of your Packeta account, available in Packeta client section, or can be provided by your account manager.
callback|function yes Function which will be called when the user confirms or cancels delivery address selection. The function will receive one argument, which will be either an Return values object if delivery address was selected, or null if selection was cancelled.
options|Object Options yes Additional configuration options of the application, see below.
inElement|DOM element no If not null, application will be displayed inside the specified DOM element. We recommend that the element has dimensions specified.

Close any previously displayed widget. This method will succeed even if none is currently open. There is no return value address.

HD Data structures

HD Options

Key Type Required Description
layout string yes Parameter for loading the widget HD. Enter value "hd".
carrierId string yes Only postcodes where the carrier deliveres can be selected. Carrier ids can be found in the Export.
language string[2] no Display user interface in language specified with ISO 639-1 code. If not set, browser preference will be used. (browser language by default or en)
country string[2] no Allowed country specified with ISO 3166-1 alpha-2 code in lower case. Either cz or sk. If no country is specified or user don’t allow location, or centerCountry is not specified, the map will center to the given country (cz by default)
county string no Province or region OBSOLETE - Use the field centerCounty instead
city string no City name OBSOLETE - Use the field centerCity instead
postcode string no Postal code OBSOLETE - Use the field centerPostcode instead
street string no Street name. If not specified, the city name will be used. OBSOLETE - Use the field centerStreet instead
houseNumber string no House number OBSOLETE - Use the field centerHouseNumber instead
centerCountry string[2] no Centers the map according to the country code, specified with ISO 3166-1 alpha-2 code in lower case and separated by comma (e.g.: au, be, gb).
centerCounty string no Province or region OBSOLETE - Use the field centerRegion instead
centerRegion string no Province or region
centerCity string no City name
centerPostcode string no Postal code
centerStreet string no Street name. If not specified, the city name will be used.
centerHouseNumber string no House number

For pre-selection of a delivery address, at least one of the houseNumber, postcode, city, country, or county options must be specified.

HD Return values

The message posted by window.postMessage(), that you can listen to using window.addEventListener():

Value Type Description
packetaWidgetMessage|bool true
address|Object Address Delivery address

HD Address

Value Type Description
country|string Country specified with ISO 3166-1 alpha-2 code in lower case.
county|string|Provinces and regions OBSOLETE - Use the field region instead
region|string Provinces and regions
city|string City name
postcode|string Postal code
street|string Street name
houseNumber|string House number
latitude|string Latitude
longitude|string Longitude
name|string OBSOLETE
suburb|string OBSOLETE