Build the kiosk shell

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

A kiosk owns the whole screen, so most of the height handling in the embedding guide does not apply here: your shell decides how big the frame is, and nothing OmniLab sends should change that. Two things still matter.

Sizing mode

The experience announces how it wants to be sized on every page load:

{ type: "sizing", mode: "content" | "viewport" }

Games report viewport — they fill whatever frame you hand them and deliberately report no height of their own. Landing pages and listings report content and follow it with resize messages carrying a measured height.

On a full-screen kiosk you can keep the frame at the screen size and ignore both. Read the mode only if your shell ever renders the frame at less than full screen, in which case a content page's resize messages are how you find out how tall it needs to be.

Drawer placement

This is the one that bites hand-written kiosk shells. When the experience opens a drawer — a reward panel, a form, a sign-in step — it sends open-modal and then renders the drawer unpositioned until the host answers.

If you never acknowledge, drawers still open — they fall back to a default full-height presentation. On a full-screen kiosk that is often acceptable, since the frame is the whole visible area and there is no sticky header to avoid. Test it on the real panel before deciding to skip the acknowledgement, particularly in portrait.

<script>
  const OMNILAB_ORIGIN = "https://experience.example.com";
  const frame = document.getElementById("omnilab-embed");

  window.addEventListener("message", (event) => {
    if (event.origin !== OMNILAB_ORIGIN) return;
    const data = event.data;
    if (!data || typeof data !== "object") return;

    if (data.type === "open-modal") {
      // Tell the drawer what it has to work with: on a full-screen kiosk
      // that is simply the frame itself.
      frame.contentWindow.postMessage(
        {
          type: "ready-to-open-modal",
          position: 0,
          parentHeight: frame.clientHeight,
          parentWidth: frame.clientWidth,
          scrollTop: 0,
          stickyOffset: 0,
        },
        OMNILAB_ORIGIN
      );
    }
  });
</script>

Always check event.origin. A kiosk shell that acts on any message it receives will act on messages from any page the frame happens to load.

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>

Start a session as a known member with fci

fci (foreign contact identifier) carries the identifier your own customer system uses for a contact — typically the value encoded on a loyalty card barcode. Append it to the experience URL when the kiosk scans a card:

https://experience.example.com/<campaign-public-link>?fci=<scanned-value>&embedded=1

What OmniLab does with it:

• Presence of fci forces an authenticated session. OmniLab redirects through the organisation's configured customer identity flow instead of loading the experience anonymously, and carries the original query string through the redirect.
• If the identifier resolves to a contact, the visitor lands in the experience already signed in, and participation is attributed to that contact.
• If it does not resolve, OmniLab shows a blocking dialog and the visitor cannot continue. There is no anonymous fallback.

fci is also read from the Referer header on the experience's own API calls, so it keeps applying to requests made after the initial page load.

The dialog's title and body are overridable through the experience's custom labels (fci.identity.error.title and fci.identity.error.description), so you can replace the default wording with something that tells the visitor what to do at the kiosk.

For anonymous kiosk sessions, omit fci entirely and put an acquisition form on the touchpoint. The visitor completes it on the kiosk keyboard before playing.

Detect an abandoned session with omnilab:idle

A kiosk left mid-game blocks the next visitor. The experience can tell the wrapper that nobody has touched the screen, so the wrapper can offer to reset.

The work splits cleanly in two, and the split follows the frame boundary:

Neither half is built-in platform behaviour, and OmniLab does not ship the parent-side half at all. The code below is reference material for whoever builds the kiosk application — it lives in their codebase, runs in their shell, and is their responsibility to implement, test, and maintain. Treat it as a specification to hand over, not as something you install.

The in-frame half is an organisation script that an admin adds under the Global organisation, scoped to the campaigns that run on kiosks. See Writing organisation scripts for how these are written and installed.

The script inside the experience

<script>
(function () {
  // Only run on campaigns that actually run on a kiosk.
  const TRIGGER_STRINGS = ["summer-experience-kiosk", "back-to-school-2026-kiosk"];

  const shouldActivate = TRIGGER_STRINGS.some((trigger) =>
    window.location.href.includes(trigger)
  );
  if (!shouldActivate) return;

  const IDLE_TIMEOUT = 10000;
  let timer;

  function sendIdle() {
    window.parent.postMessage(
      { type: "omnilab:idle", timestamp: Date.now() },
      "*"
    );
    reset();
  }

  function reset() {
    clearTimeout(timer);
    timer = setTimeout(sendIdle, IDLE_TIMEOUT);
  }

  ["click", "mousedown", "mousemove", "keydown", "scroll", "touchstart", "touchmove"].forEach(
    (e) => document.addEventListener(e, reset, { passive: true })
  );

  reset();
})();
</script>

Behaviour worth knowing before you build the parent side:

• The allowlist is a substring match on the full URL. Each entry is checked with includes() against window.location.href, so a campaign public link works as an entry. Anything not matching returns immediately and installs no listeners, which is what keeps the script inert on your non-kiosk campaigns.
• The timer restarts after each signal. An abandoned kiosk emits omnilab:idle every 10 seconds, not once. Your listener has to tolerate repeats.
• Any of seven activity events resets the timer — click, mousedown, mousemove, keydown, scroll, touchstart, touchmove — registered passively on document.
• Only interaction inside the frame counts. A visitor touching the kiosk's own chrome does not reset this timer.

Install it as an iframe-only script on the visit trigger, and republish every affected campaign afterwards. A saved script that has not been republished does not reach the live experience.

What the kiosk application has to implement

Everything below runs in the kiosk shell, not in OmniLab. Hand it to your kiosk provider as the contract their side has to satisfy.

let modalOpen = false;
let countdownInterval = null;

window.addEventListener("message", (event) => {
  if (event.data?.type === "omnilab:idle" && !modalOpen) {
    showInactivityModal();
  }
});

function showInactivityModal() {
  modalOpen = true;
  let countdown = 10;
  updateCountdown(countdown);

  countdownInterval = setInterval(() => {
    countdown -= 1;
    updateCountdown(countdown);
    if (countdown <= 0) closeIframe();
  }, 1000);
}

function stayInSession() {
  clearInterval(countdownInterval);
  modalOpen = false;
  hideModal();
}

function closeIframe() {
  clearInterval(countdownInterval);
  modalOpen = false;
  document.getElementById("omnilab-embed").src = "";
  showWelcomeScreen();
}

The modalOpen guard is not optional. Without it, the repeating signal restarts the countdown every 10 seconds and the modal never times out.

Budget for the full reset when you size the flow: 10 seconds of silence before the first signal, plus whatever countdown your modal runs. A 10-second countdown means an abandoned kiosk frees itself after roughly 20 seconds.

What the modal should offer

The kiosk provider designs and builds this. OmniLab has no control over it and cannot style it.

Clearing the frame's src is what actually ends the session — the OmniLab experience has no way to unload itself, so if the kiosk application does not act on the signal, nothing happens at all.

Host responsibilities outside OmniLab

Your wrapper should take care of:

• device-level permissions for camera, microphone, and geolocation
• the inactivity modal and the decision to reset the frame — OmniLab can signal idleness, but only the wrapper can close the session
• 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, and that your listener checks event.origin.
• Open a game and confirm the frame is already at full screen — a viewport-sized page sends no height, so a shell that waits for one shows nothing.
• 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.

Kiosk URL patterns and query parameters

Kiosk deployments typically use one of these URL patterns. Always include embedded=1 when loading in an iframe or WebView.

For JavaScript player tag deployments, the host page URL controls which campaign loads:

• https://kiosk.example.com/?id=summer-campaign
• https://kiosk.example.com/?id=summer-campaign%3Fc%3D<touchpoint-id>%26embedded%3D1

URL-encode any nested query string before publishing the link to the player tag.

Related