1. Quick Start — Integration in 5 Minutes

The fastest way to deploy the widget in an e-shop is to copy the ready-made code from the widget admin panel. For each API key, the admin provides a default HTML snippet containing the correct loader URL and a properly configured <ppl-access-point-widget> element with your API key. Simply paste this code into the appropriate place in your e-shop (e.g. the checkout template, order detail page, etc.) and the widget will be automatically initialized when the page loads.

In the widget admin, switch to the Widget Code tab. A generated HTML snippet ready to copy will appear — clicking the Copy button transfers the entire code to the clipboard:

The snippet consists of two parts that are placed in different locations on the page:

<script> tag with the loader — ideally belongs in the <head> section of the host page. The loader downloads all required widget assets (JS, CSS, runtime configuration) and registers the <ppl-access-point-widget> Custom Element. The script can also be placed at the end of <body>, but placing it in <head> is recommended so the widget is ready as early as possible.

The <ppl-access-point-widget> element — belongs exactly where the widget should be displayed in the DOM (typically in the checkout template or the shipping selection section). The api-key attribute links the widget to the specific settings in the admin; the id attribute enables convenient JavaScript access (document.getElementById("pplWidget")) — for example, for listening to events or calling the open() method in modal mode.

The code generated in the admin contains a real API key tied to your organization — this key must be kept unchanged. In a production deployment, it is also advisable to store the API key in your e-shop configuration (e.g. as a template variable) rather than hardcoding it in multiple places.

What You Can Configure in the Admin Before Copying the Code

The widget admin allows you to pre-configure the widget's default server-side behavior so the copied HTML snippet stays minimal with no further changes needed on the host page. Upon loading, the widget makes an API call with api-key and fetches the active configuration from the admin. The most important options include:

Add domain whitelist — a list of domains from which the widget may be loaded. This secures the API key against misuse on third-party sites. Add all domains where the widget will actually be displayed (production domain, staging, and localhost for development).

Product type — choose between Custom Settings (explicit list of access point types) and Smart 2 Box (automatic type selection based on PPL logic). The product type determines which access points will be offered in the widget.

Access point types — select the specific box and branch types to be available in the widget: AlzaBox, ParcelBox, ParcelShop. This setting only applies when the product type is set to Custom Settings.

Display mode (viewMode) — the widget's default mode is modal (the widget is hidden and opens after calling the open() method). In the admin, the mode can be switched to inline (the widget appears directly in the page flow). This setting is applied automatically based on api-key and does not need to be duplicated in the config attribute. If a specific page needs a different mode than the one set in the admin, it can be overridden via config (e.g. config='{"viewMode":"inline"}').

Other admin parameters — default interface language, default country, default map coordinates, etc. All these values are applied automatically based on api-key and do not need to be specified in the config attribute on the host page.

Note: Until changes in the admin are saved and activated (the Activate button at the top of the screen), the widget on the host page uses the last activated configuration version. This allows you to safely prepare changes without the risk of them immediately affecting production.

When to Manually Edit the Code from the Admin

If the default values from the admin are sufficient, the code does not need to be modified at all. Manual edits to the admin snippet typically make sense in the following cases:

You want to override some default setting on a specific page (e.g. force viewMode: "inline" on a page where the widget should be embedded directly in the layout, even if the admin has modal set). In that case, add a config attribute with a JSON object to the element — see chapter 2.4 for details.

You are integrating the widget into a React / Vue / Angular application where framework-specific syntax is needed instead of plain HTML (e.g. ref in React for DOM node access) — see chapters 5 and 6.

You need to open the widget programmatically (a "Select Pickup Point" button), listen to events (ppl-accesspointwidget-select, ppl-accesspointwidget-ready), or change configuration at runtime.

In all these cases, the default code from the admin remains the foundation — you simply add attributes (config, event listeners) to the snippet, or wrap it in an appropriate framework component. The rest of the settings still come from the admin based on api-key.

1.2 Minimal Example (Inline Mode)

The widget is displayed directly in the page flow as part of the page. The widget's default mode is modal — for inline display you must either have the mode switched to inline in the widget admin (by api-key), or force it on the element via config='{"viewMode":"inline"}'. Language, country, and other parameters are also inherited from the admin, so the minimal example below assumes the admin has the mode set to inline:

Note: Only use the config attribute if you want to override a default admin setting for a specific page — typically when the admin has modal mode set but a specific page needs the widget displayed inline (config='{"viewMode":"inline"}'). See chapter 2.4 for details.

The widget is hidden and appears as a fullscreen overlay when a button is clicked. Modal is the widget's default mode, so if the admin hasn't switched it to inline, the config attribute is not needed — just provide api-key. In the example below, config='{"viewMode":"modal"}' is specified explicitly so the example works regardless of the current admin setting:

Loading sequence:

The browser downloads the loader script from https://www.ppl.cz/accesspointwidget/loader.js

The loader fetches configuration.js with runtime configuration (API URL, keys)

The loader automatically downloads the hashed JS and CSS widget files

The <ppl-access-point-widget> Custom Element is registered

The widget makes an API call to the PPL server to verify api-key and fetch configuration

After successful initialization, the ppl-accesspointwidget-ready event is emitted

The widget is ready to use

1. Quick Start — Integration in 5 Minutes

1.1 Getting the Default Code from the Widget Admin

What You Can Configure in the Admin Before Copying the Code

When to Manually Edit the Code from the Admin

1.2 Minimal Example (Inline Mode)

1.4 What Happens When the Widget Loads

1. Quick Start — Integration in 5 Minutes

1.1 Getting the Default Code from the Widget Admin#

What You Can Configure in the Admin Before Copying the Code#

When to Manually Edit the Code from the Admin#

1.2 Minimal Example (Inline Mode)#

1.3 Minimal Example (Modal Mode)#

1.4 What Happens When the Widget Loads#

1.1 Getting the Default Code from the Widget Admin

What You Can Configure in the Admin Before Copying the Code

When to Manually Edit the Code from the Admin

1.2 Minimal Example (Inline Mode)

1.3 Minimal Example (Modal Mode)

1.4 What Happens When the Widget Loads