Introducing Pericles: The London Dynamics Configurator

Pericles (/ˈpɛrɪkliːz/) is the project name for the London Dynamics 3D (and 2D) configurator service. Designed with versatility and ease of integration in mind, this package allows you to embed a dynamic and interactive scene directly onto your web page using a simple Web Component.

The Pericles project includes:

• Pericles JS: JavaScript widget with a common implementation API (legacy)
• Pericles Web Component: A Web Component following HTML standards (you are here)
• Pericles React: TBA

Demo

👉 Try it out in our storybook 👈

Installation

npm install @londondynamics/pericles-webcomponent

Usage

<script
  type="module"
  src="node_modules/@londondynamics/pericles-webcomponent/dist/configurator.js"
></script>

<ld-configurator customerId="your-customer-id" sku="your-scene-sku">
</ld-configurator>

See all our examples in action.

Configuration

The Pericles web component requires the following attributes:

• customerId: Your customer ID
• sku: The SKU of the scene you wish to embed OR
• sceneId: The permanent ID of the scene you wish to embed OR
• hash: The hash code of a previously saved configuration

[!TIP] For more information on configuring the visualiser, please visit the SDK Documentation

Analytics (integrationType)

The web component always appends integrationType=webcomponent and websdk=1 to the Pericles iframe URL. Pericles sends integrationType on GA pageviews so analytics can distinguish web component embeds from the JS widget, plain iframes, and direct visits.

How communication works

This package is part of the Web SDK: it embeds Pericles in an iframe on your page so you can call methods and listen for events from JavaScript. If you only need the configurator UI without programmatic control from the host page, you can link to or navigate to Pericles directly instead (no iframe).

<ld-configurator> does not talk to the 3D viewer directly. It loads Pericles in an iframe and exchanges messages with it over the browser postMessage API. Pericles acts as the bridge: it receives your commands, calls methods on the Agora React component, and either replies or pushes events back.

Host page  →  <ld-configurator>  →  Pericles iframe  →  Agora

Calling methods

When you call a method on <ld-configurator>, the component posts a message into the iframe:

• Setters (setFeature, setSelection, resetCamera, …) use _postMessage — fire-and-forget. Pericles may push a change or log event back, which the web component re-emits as a DOM CustomEvent on the element.
• Getters (getCurrentSource, getCurrentHash, …) use _pingpongPostMessage — the component adds a messageId, waits for a matching reply from the iframe, parses the JSON result, and resolves a Promise (or runs your callback).

Wait for the ready event before calling getters or setters. Pericles sends { type: 'ready', ... } once Agora is mounted.

Listening for events

Inbound push messages (ready, load, error, change, cameraChange, log) are handled in _handleMessage and dispatched as DOM events on <ld-configurator>. For log messages, the logType field becomes the event name (e.g. click, qrOpen, arOpen).

Message protocol

| Field | Direction | Purpose | |---|---|---| | type | both | Command or event name (setFeature, currentSource, ready, …) | | messageId | request + response | Correlates ping-pong pairs (Date.now() on send) | | result | response | JSON-stringified return value for getters | | other fields | request | Payload (featureId, variantId, selection, …) |

Inbound messages are validated against event.origin === this.host (default https://configurator.v2.londondynamics.com).

Implementation: src/configurator.ts (_postMessage, _pingpongPostMessage, _handleMessage).

See also: Pericles README — How communication works · pericles-js README

Adding a new API method

See the Pericles README → Adding a new API method for the full end-to-end checklist (Agora ref → Pericles bridge → client packages).

Releasing

1. Bump the version in package.json and commit (e.g. 2.4.2).
2. Create and push a matching tag:

git tag v2.4.2
git push origin v2.4.2

3. The release workflow will validate the tag, publish to npm, and create a GitHub Release.

4. Manually upload the built dist/ files to S3 so the web component is also available from:

   https://web-packages.londondynamics.com/webcomponent/v/latest/configurator.js

The tag must match package.json exactly (v2.4.2 ↔ "version": "2.4.2"). Publishing the same version twice will fail.

Unlike @london-dynamics/types (GitHub Packages), this package publishes to public npm via Trusted Publishing (OIDC).

GitHub and npm settings

• Required (npm): Package settings → Trusted Publisher → GitHub Actions → org london-dynamics, repo pericles-webcomponent, workflow release-package.yml (filename must match exactly). A 404 on publish usually means this is missing or misconfigured.
• Alternative (npm): Add an NPM_TOKEN repository secret (automation token with publish access to @londondynamics). When set, the workflow uses token auth instead of Trusted Publishing.
• Required (GitHub): Settings → Actions → General → Workflow permissions → Read and write permissions.
• Recommended: Settings → Tags → protection rule for v*.
• No longer needed: Creating a GitHub Release manually before publish.

License

This project is licensed under the terms of the MIT license.