Integration documentation

01 / START

Choose how to embed.

BlueBox prepares a digital twin from your machine’s materials and supplies its URLs and IDs for deployment. The examples below use our public reference models.

You can keep your existing website. It must allow an iframe or custom JavaScript and permit the embed in its security policy.

02 / HTML

Paste. Open. Explore.

1. Add an HTML block where you want the machine to appear.
2. Paste the code below and save the page.
3. Open the page on desktop and mobile. Check orbiting the view and machine motion.

<iframe
  src="https://blueboxsimulation.com/blueboxweb/twin/embed?machine=jubilee-solder&lang=en&presentation=scene"
  title="Soldering robot digital twin"
  loading="lazy"
  style="display:block;width:100%;height:460px;border:0"
></iframe>

presentation=scene shows only the 3D scene. Remove it to include controls, information and available configuration options. lang=pl / lang=en selects the language; cfg passes a selected configuration.

Allow more height for the full interface, for example 720px on desktop and 1100px on mobile, or retain scrolling inside the iframe. The visible source link preserves attribution for the demo models.

03 / JAVASCRIPT

A component in your layout.

Load the module once per page. Then add a bluebox-twin element for each prepared machine. Shadow DOM scopes the internal stylesheet.

<script type="module"
  src="https://blueboxsimulation.com/blueboxweb/twin/bluebox-twin.js"></script>

<bluebox-twin
  machine="router5"
  brand="bluebox-en"
  lang="en"
  base="https://blueboxsimulation.com/blueboxweb/twin/"
  share-url="https://blueboxsimulation.com/blueboxweb/en/maszyny/router5?cfg={cfg}"
  style="display:block;height:720px"
></bluebox-twin>

<a href="https://blueboxsimulation.com/blueboxweb/en/maszyny/router5#product-documents"
  target="_blank" rel="noopener">Model sources & licenses</a>

The full interface grows vertically in a narrow container. For a scene-only view, set presentation="scene", tabindex="0" and an aria-label, and give its container an explicit height. Space pauses/resumes the focused scene. Reduced-motion users start with the scene paused.

04 / EVENTS

React to configuration changes.

Attach listeners before inserting the component or loading the module. twinready reports a loaded model, twinerror a loading failure, and configchange supplies the configuration in event.detail.cfg. Configurable machines also emit it on initial load.

const twin = document.querySelector('bluebox-twin');

twin.addEventListener('twinready', () => {
  console.log('Ready');
});

twin.addEventListener('twinerror', () => {
  // Show a loading error and a retry action.
});

twin.addEventListener('configchange', event => {
  console.log(event.detail.cfg);
});

These events belong to the JavaScript component. A cross-origin iframe does not expose them to its parent. There is currently no postMessage API or public start/pause/camera methods; use the visible controls and scene keyboard controls.

05 / REFERENCE

Component attributes.

Changing machine, brand, base, lang or presentation reloads the twin. Unknown or incompatible cfg values are normalized by the machine’s rules.

06 / HANDOFF

What should your team prepare?

Constructor / machine specialist

• CAD files, units and identification of moving parts.
• Axes and travel limits, cycle description and material showing the actual process.
• Equipment variants and selection rules if the model should be configurable.

Developer / agency

• Website URL and technology, access to an HTML block or code, and CSP requirements.
• Embed placement, target dimensions, language and inquiry destination.
• Testing on target devices before publishing.

Marketing / product owner

Identify the process buyers should understand, approve product names and information, and assign the inquiry recipient. Your agency can continue managing the website; BlueBox supplies the agreed interactive component.

07 / TROUBLESHOOTING

When something goes wrong.

This guide covers embedding prepared models. It does not expose source CAD, connections to PLC/ERP/CRM systems or a public machine editor.

Integration support: tomasz@blueboxsimulation.com