Kiosk integration (technical deep-dive)

This guide explains the technical parts of keeping OmniLab inside a kiosk shell or wrapper app. Use it together with the public embedding articles when your team controls the host page, the WebView container, or the device runtime around OmniLab.

Choose the right wrapper model

Use embed-ready URLs

Start from the same OmniLab URLs documented in the public embedding guides:

• campaign landing page when the wrapper should show several experiences
• direct touchpoint URL when the wrapper should launch one experience immediately
• embedded=1 when you are using a manual iframe or WebView embed path

Parent-child messaging you should support

OmniLab can send postMessage events to the parent wrapper. The most important one for most kiosk builds is resize.

<script>
  window.addEventListener("message", (event) => {
    console.log("OmniLab message", event.origin, event.data);

    if (event.data?.type === "resize" && event.data?.target === "body") {
      const iframe = document.getElementById("omnilab-embed");
      if (iframe && typeof event.data?.data?.height === "number") {
        iframe.style.height = event.data.data.height + "px";
      }
    }
  });
</script>

In more advanced iframe shells, OmniLab can also emit modal-related messages such as open-modal and close-modal. If your wrapper needs to participate in that layout, validate the exact message flow in staging with OmniLab before you ship.

JavaScript player pattern

When one kiosk page should load different campaigns, use the OmniLab player tag with a query parameter such as id.

<div id="omnilab-container"></div>

<script>
  (function (b, o, n, u, s) {
    var a, t;
    a = b.createElement(u);
    a.async = 1;
    a.src = s;
    t = b.getElementsByTagName(u)[0];
    t.parentNode.insertBefore(a, t);
    o[n] = o[n] || [];
  })(document, window, "_om_async", "script", "https://<omnilab-script-host>/omplayer.js");

  _om_async.push([
    "init",
    {
      domain: "experience.example.com",
      targetId: "omnilab-container",
      queryParam: "id",
    },
  ]);
</script>

Host responsibilities outside OmniLab

Your wrapper should take care of:

• device-level permissions for camera, microphone, and geolocation
• inactivity timers and kiosk home-screen behavior
• scanner hardware or external peripherals
• session handoff between your shell and OmniLab
• logging and remote support diagnostics for the container itself

Debug checklist

• Confirm the wrapper loads the correct campaign or touchpoint URL.
• Verify the iframe or WebView can receive camera and other required permissions.
• Check that postMessage events from OmniLab reach the parent shell.
• Test drawers, keyboards, and modal flows inside the real kiosk container, not only in a standalone browser tab.
• Log the raw OmniLab messages during staging so you can compare expected and actual behavior quickly.

Related