2. Embedding the Widget into a Page

2.1 Loader Script

The widget is loaded via a single loader script that automatically downloads the current version of JS and CSS files:

The loader handles:

Loading the runtime configuration (configuration.js) with API URL and keys

Downloading the current version of JS and CSS files (with cache-busting hash)

Registering the <ppl-access-point-widget> Custom Element

Preventing duplicate loading (if the script is inserted multiple times)

Fallback UI on load error

Note on URL: The src attribute on the <script> element works with any URL that returns JavaScript content with the correct Content-Type: application/javascript. The URL does not need to end with .js — the browser follows the response header, not the URL extension.

After the loader is loaded, the <ppl-access-point-widget> element is available as a regular HTML tag.

2.2 Container Height Requirement

Important: The widget internally uses :host { display: block; height: 100% } in Shadow DOM. For reliable display in any environment, its parent element should have an explicitly set height (in pixels, viewport units, or via a height chain up to an element with a fixed height). In a production e-shop integration where the widget is deeply nested in the DOM alongside headers, footers, and other sections, explicit height is essential — without it, the widget may display incorrectly or collapse to minimal height.

Typical solutions — choose based on context:

a) Fixed Pixel Height (Recommended for Inline in Page Flow)

The most common and safest approach — the widget occupies a specific space in the middle of the page:

The recommended minimum height is 500–600 px for comfortable display of the map and access point list.

b) Full Viewport Height

If you want the widget to fill the entire window (e.g. a standalone map page), use viewport units — they work independently of parent heights:

Warning: A common mistake is placing the widget directly in <body> without any adjustment. By default, <body> has auto-height derived from its content, so the widget collapses. You must either set html, body { height: 100% } (height chain) or wrap the widget in <div style="height: 100vh">. If the widget "disappeared" after being added to the page, check this first.

c) Responsive Viewport Height

For flexible behavior (e.g. 80% of window height), combine viewport units with a minimum height:

Exception — modal mode: In modal mode (viewMode: "modal"), the widget creates its own fullscreen overlay and container height settings are not required. The widget manages the overlay dimensions itself, and the container in HTML remains empty with zero height.

2.3 Waiting for Element Registration

If you need to configure the widget only after its registration (e.g. when loading the script dynamically), you can use the browser API:

Alternatively, you can use the ppl-accesspointwidget-ready event, which is emitted after successful widget initialization (see chapter 4.2).

2.4 The config Attribute and Default Configuration from Admin

After loading, the widget requests its default configuration from the PPL server (endpoint GET /v1/configuration). This configuration is tied to api-key and managed in the widget admin — it typically contains the default language, country, allowed countries, viewMode (inline/modal), allowed access point types, etc.

The widget's default mode is modal. In the admin, the mode can be switched to inline as needed. The admin settings are applied automatically based on api-key and do not need to be duplicated in config.

The config attribute is used to override (or narrow) the default configuration from the admin — for parameters that differ for a specific page or order compared to the global settings. A typical use case is viewMode: if the admin has modal set but a specific page needs the widget displayed inline (or vice versa), this can be forced via config='{"viewMode":"inline"}' or config='{"viewMode":"modal"}'. Similarly, config is used to pass package dimensions from the current cart, a pre-selected access point, the customer's dynamic country, etc.

The only required attribute is api-key. If the config attribute is omitted, the widget uses exclusively the default configuration from the admin.

Recommended approach:

First, configure preferred values (default language, country, viewMode, allowed AP types…) in the widget admin for your api-key.

In HTML, integrate the widget with only the api-key attribute.

Use the config attribute only where a specific integration must differ from the global settings (typically dynamic cart data or a page-level override).

A complete list of parameters that can be overridden via config can be found in chapter 7.5.

2.5 The config Attribute Format — Strict JSON

The config attribute requires valid JSON (not a JavaScript object). If the JSON is invalid, config is not parsed and the widget uses only the server configuration. The error is shown in the browser console.

Most common mistakes:

Other common mistakes:

Single quotes — {'viewMode': 'modal'} — JSON requires double quotes

Comments — // comment or /* */ are not allowed in JSON

2. Embedding the Widget into a Page

2.1 Loader Script#

2.2 Container Height Requirement#

a) Fixed Pixel Height (Recommended for Inline in Page Flow)#

b) Full Viewport Height#

c) Responsive Viewport Height#

2.3 Waiting for Element Registration#

2.4 The config Attribute and Default Configuration from Admin#

2.5 The config Attribute Format — Strict JSON#