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:
- 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)
- 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. |
Packeta.Widget.close()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 | centerCounty instead |
city |
string |
no | centerCity instead |
postcode |
string |
no | centerPostcode instead |
street |
string |
no | centerStreet instead |
houseNumber |
string |
no | 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 |
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 | |
city|string |
City name | |
postcode|string |
Postal code | |
street|string |
Street name | |
houseNumber|string |
House number | |
latitude|string |
Latitude | |
longitude|string |
Longitude |