Widget
This document details the standard implementation of Packeta Home Delivery (HD) address selection utilizing an embeddable application. We recommend embedding the application using the integration library outlined below.
Intended audience
This manual is intended for technically advanced internet stores which require and are able to implement custom interaction with the widget.
Specifically, the following skills are required:
- Basic JavaScript programming
- Basic HTML/CSS knowledge
Getting started – examples
- Register yourself at Packeta Client section, and get your API key at User support at Packeta Client section, or ask your account manager for the API key.
- We offer an integration library library.js to simplify the process of embedding the widget into your website. Please remember it won't have an automatic updates that way.
Here are some examples using the library: simple, complex, combination
Supported browser versions
List of minimal supported browser versions:
- Google Chrome 79
- Mozilla Firefox 79
- Microsoft Edge 18
- Safari 11
- Opera 70
Basic embeddable application implementation details
The embeddable application exists within an isolated iframe, which can only interact with your main webpage through sending messages via window.postMessage().
The application will utilize the parameters of the pick function, denoted further below, as query string parameters for the iframe. For instance, https://hd.widget.packeta.com/v6/#/?layout=hd&carrierId=80&apiKey=XXXXXXXXXXXXX&country=cz,sk (note this is just an example - you must input your own API Key for the widget to function properly)
Permissions for Iframe:
- Recommended:
sandbox="allow-scripts allow-same-origin" allow="geolocation" - Minimal requirement:
sandbox="allow-scripts" - Be aware that geolocation is only available if your online store operates over https (not just http)
- Persistence of cookies
The shopping cart has two unique operational modes:
- Selection of the pick-up point happens within a modal dialog (this opens after the customer opts for delivery to a Packeta pick-up point, or via a button next to such a delivery method)
- Inline UI controls, incorporated as part of the selection process for the delivery method The application supports both modes. When implementing the latter, ensure compatibility with mobile phones and tablets through thorough testing.
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.
Data structures
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 deliveries can be selected. Carrier ids can be found in the carriers list. |
language | string[2] | no | Display user interface in language specified with ISO 639-1 alpha-2 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) |
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). |
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 |
county | string | no | Deprecated. Use centerRegion instead. |
city | string | no | Deprecated. Use centerCity instead. |
postcode | string | no | Deprecated. Use centerPostcode instead. |
street | string | no | Deprecated. Use centerStreet instead. |
houseNumber | string | no | Deprecated. Use centerHouseNumber instead. |
centerCounty | string | no | Deprecated. Use centerRegion instead. |
For pre-selection of a delivery address, at least one of the houseNumber, postcode, city, country, or county options must be specified.
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 |
Address
| Value | Type | Description |
|---|---|---|
country | string | Country specified with ISO 3166-1 alpha-2 code in lower case. |
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 |
county | string | Deprecated. Use region instead. |
name | string | Deprecated. |
suburb | string | Deprecated. |