Développer l'application de la borne
Développez l'application de la borne autour d'une expérience OmniLab : son chargement, son adresse, la connexion et la réinitialisation après inactivité.
Cette page s'adresse au développeur de l'application de la borne. L'expérience relève d'OmniLab ; l'écran, le lecteur et tout ce qui entoure l'expérience sont de votre ressort.
Choisir le mode de chargement
| Configuration | Fonctionnement | À utiliser quand |
|---|---|---|
| Une WebView | La WebView de l'app de la borne ouvre l'adresse de l'expérience comme page principale | Votre borne exécute une app qui contrôle l'écran. C'est la configuration la plus simple, et celle à privilégier. |
| Une iframe dans une page web de borne | Votre page contient une iframe, écrite à la main ou par le tag JavaScript | Votre borne affiche dans un navigateur une page que vous hébergez |
Une iframe doit appartenir au même site que la page de borne
Dans une iframe, la connexion ne fonctionne que si l'expérience est diffusée depuis un sous-domaine du domaine de la page de borne. Pour une page sur kiosk.lindenhall.example, diffusez l'expérience depuis play.lindenhall.example : voir Domaine personnalisé. Depuis tout autre domaine, le navigateur considère l'iframe comme un contenu tiers et bloque ses cookies. Une carte de fidélité scannée bute alors systématiquement sur la vérification d'identité : les valeurs des cartes semblent erronées, alors que c'est la configuration qui est en cause. Le tag JavaScript crée le même type d'iframe : la règle s'applique donc aussi à lui.
Dans une iframe, évitez les points de contact qui demandent au visiteur de se connecter à l'écran. Avec le tag JavaScript, cette connexion remplace toute votre page de borne. Dans une iframe que vous écrivez vous-même, elle s'exécute dans l'iframe, et certains fournisseurs d'identité refusent de s'y charger : vérifiez sur un appareil.
URLs et paramètres de borne
Partez du lien du point de contact dans Studio. Ajoutez l avec la langue par défaut de la borne, puis un paramètre pour chaque session :
| Session | Ajouter | Exemple |
|---|---|---|
| Un membre scanne une carte de fidélité | l, puis fci= et la valeur scannée | https://play.lindenhall.example/lindenhall-autumn-kiosk?c=a315&l=en&fci=6345789012 |
| Un visiteur démarre sans carte | l, puis login=0 | https://play.lindenhall.example/lindenhall-autumn-kiosk?c=a315&l=en&login=0 |
l est important sur un écran partagé. L'expérience mémorise le choix de langue d'un visiteur sur l'appareil pendant 30 jours : sans l, le visiteur suivant en hérite.
login=0 déconnecte la personne qui a utilisé la borne avant. Sans lui, le visiteur suivant risque de reprendre la session du précédent. Un nouveau scan fci démarre toujours une nouvelle connexion : il n'a donc pas besoin de login=0.
N'ajoutez pas embedded=1, ni dans une WebView, ni dans une iframe fixée à l'écran. Il est prévu pour une page qui adapte la hauteur de l'iframe à l'expérience et défile jusqu'à chaque panneau. Le tag JavaScript fait les deux, et ajoute embedded=1 lui-même. Ajouté ailleurs, il provoque l'ouverture des panneaux hors de l'écran dès que le visiteur fait défiler une longue page.
Pour fixer la variante, ajoutez v. La liste complète se trouve dans URLs et paramètres d'intégration.
Charger différentes campagnes depuis une page de borne
Le tag JavaScript permet à une page de borne de charger la campagne indiquée dans sa propre adresse. Il ajoute embedded=1, et login=0 par défaut : n'incluez donc aucun des deux dans id. Il dimensionne aussi l'iframe selon l'expérience et fait défiler votre page jusqu'à chaque panneau. Il ne donne à son iframe aucun accès à la caméra ni à la localisation : utilisez-le seulement pour des expériences qui n'ont besoin d'aucun des deux.
<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://cdn.21-digital.com/omplayer.js");
_om_async.push([
"init",
{
domain: "play.lindenhall.example",
targetId: "omnilab-container",
queryParam: "id",
},
]);
</script>C'est alors l'adresse de la page de borne qui détermine la campagne :
https://kiosk.lindenhall.example/?id=lindenhall-autumn-kioskouvre la page d'accueil, si la campagne en a une.https://kiosk.lindenhall.example/?id=lindenhall-autumn-kiosk%3Fc%3Da315%26l%3Denouvre un point de contact, en anglais.
Encodez toute la valeur de id en URL quand elle contient plus d'un paramètre. L'adresse du script de Staging et toutes les options se trouvent dans la Référence du tag JavaScript.
Démarrer et terminer une session avec le tag
Le tag lit id une seule fois, au chargement de la page de borne. Démarrez donc chaque session en chargeant la page de borne avec l'id de cette session, et terminez-la en chargeant la page sans id :
const KIOSK_PAGE = "https://kiosk.lindenhall.example/";
const TOUCHPOINT = "lindenhall-autumn-kiosk?c=a315&l=en";
function startSession(scannedValue) {
const experience = scannedValue ? TOUCHPOINT + "&fci=" + scannedValue : TOUCHPOINT;
window.location.assign(KIOSK_PAGE + "?id=" + encodeURIComponent(experience));
}
function endSession() {
window.location.assign(KIOSK_PAGE);
}Sans id, le tag ne charge rien : la page affiche donc votre écran d'accueil. Une session sans carte reçoit le login=0 du tag, et démarre donc sans connexion.
Les valeurs scannées composées de lettres, de chiffres, de tirets et de points passent intactes par id. Une valeur contenant &, #, % ou + arrive tronquée ou modifiée : pour celles-ci, écrivez l'iframe vous-même, comme dans la page de borne ci-dessous.
La fenêtre d'inactivité et le listener message de la page de borne ci-dessous fonctionnent ici sans modification, avec le endSession() écrit ci-dessus. Passez inSession à true quand l'adresse de la page contient un id.
Démarrer une session en tant que membre connu avec fci
Ajoutez la valeur scannée comme fci, encodée en pourcentage. Ce que voit le visiteur, et comment reformuler la boîte de dialogue pour une carte inconnue, sont décrits dans Transmettre un client connu à une expérience.
Deux points à régler avant les tests sur borne :
- L'intégration de reconnaissance. Les membres ne peuvent se passer de l'écran de connexion qu'avec une intégration de reconnaissance, mise en place pour chaque campagne. Demandez à votre Customer Success Manager de confirmer qu'elle fonctionne avec votre système d'identité, dans l'environnement que vous testez.
- Les adresses par lesquelles passe la connexion. La connexion quitte brièvement le domaine de l'expérience. Une WebView qui n'ouvre que des adresses approuvées doit aussi les autoriser : voir Développer la WebView.
Pour des sessions anonymes, démarrez avec login=0 et placez un formulaire d'inscription sur le point de contact. Le visiteur le remplit sur le clavier de la borne avant de jouer.
Messages de mise en page
Dans une iframe, l'expérience envoie sa hauteur à votre page. Une iframe fixée à l'écran, comme dans l'exemple ci-dessous, peut l'ignorer. Les jeux remplissent l'iframe, une page plus longue défile à l'intérieur, et les panneaux s'ouvrent à l'écran, comme dans le navigateur d'un téléphone.
Une page de borne qui adapte la hauteur de l'iframe à l'expérience, et qui défile, a besoin de embedded=1 et de tous les messages de Messages entre la page et l'expérience. Le tag JavaScript les gère pour vous. Dans une WebView, il n'y a pas de page autour de l'expérience : il n'y a donc rien à gérer.
Détecter une session abandonnée avec omnilab:idle
Une borne laissée en pleine partie bloque le visiteur suivant. Un petit script dans l'expérience détecte que personne n'a touché l'écran, et prévient la borne. La borne propose alors une réinitialisation.
| Côté | Rôle | Qui le développe |
|---|---|---|
| Dans l'expérience | Surveille l'activité et envoie omnilab:idle | Vous écrivez le script. Un administrateur Studio l'ajoute une fois. |
| Autour de l'expérience | Reçoit le signal, affiche la fenêtre, met fin à la session | Vous, dans l'application de la borne |
Aucune de ces deux parties n'est intégrée au produit. Les deux se trouvent dans votre code, et c'est à vous de les développer, de les tester et de les maintenir.
Ajouter le script d'inactivité
<script>
(function () {
// Le chemin de chaque campagne diffusée sur une borne : son lien après le domaine.
const KIOSK_CAMPAIGNS = ["/lindenhall-autumn-kiosk", "/lindenhall-christmas-kiosk"];
const IDLE_TIMEOUT = 10000; // millisecondes sans contact
const path = window.location.pathname;
if (!KIOSK_CAMPAIGNS.some((c) => path === c || path.startsWith(c + "/"))) return;
let timer;
function sendIdle() {
// Dans une iframe, ce message atteint la page de borne. Dans une WebView, il atteint
// la fenêtre de cette page, où le script injecté par l'app de la borne le récupère.
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(
(type) => document.addEventListener(type, reset, { passive: true })
);
reset();
})();
</script>À savoir avant de développer le côté borne :
- La liste des campagnes est comparée au chemin. Chaque entrée est le lien d'une campagne après le domaine, comme
/lindenhall-autumn-kiosk. Sur toute autre campagne, le script s'arrête aussitôt. - Le signal se répète. Une borne abandonnée envoie
omnilab:idletoutes les 10 secondes, pas une seule fois. - Seules les interactions dans l'expérience comptent. Un appui sur votre propre fenêtre ne réinitialise pas ce minuteur.
- Il s'exécute partout où une campagne listée s'ouvre. Sur un téléphone, rien n'écoute le signal : il ne se passe donc rien.
Transmettez le code à un administrateur Studio. Il l'ajoute dans l'onglet Scripts de l'Organisation globale, avec le champ Contexte du script réglé sur ALL et le champ Événement déclencheur sur VISIT : voir Ajouter un script. Avec ALL, il s'exécute dans une WebView comme dans une iframe ; la liste des campagnes l'exclut de toutes les autres campagnes. Chaque campagne qu'il couvre doit ensuite être republiée.
Recevoir le signal dans une page web de borne
Cette page est une application de borne complète pour la configuration en iframe. Elle affiche un écran d'accueil, démarre une session sur un scan ou un appui, et gère la fenêtre d'inactivité. Son bouton Home met fin à la session à tout moment. Remplacez l'adresse par le lien de votre point de contact.
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Lindenhall kiosk</title>
<style>
html, body { margin: 0; height: 100%; overflow: hidden; font-family: sans-serif; }
#welcome, #omnilab-embed, #idle-modal { position: fixed; inset: 0; }
#welcome { display: flex; align-items: center; justify-content: center; font-size: 5vh; }
#omnilab-embed { width: 100%; height: 88vh; border: 0; }
#home-button { position: fixed; left: 0; bottom: 0; width: 100%; height: 12vh; font-size: 4vh; }
#idle-modal { display: flex; flex-direction: column; align-items: center; justify-content: center;
gap: 3vh; background: rgba(0, 0, 0, 0.8); color: #fff; font-size: 4vh; }
#idle-modal button { font-size: 3vh; padding: 2vh 6vh; }
[hidden] { display: none !important; }
</style>
</head>
<body>
<div id="welcome">Scan your card, or touch the screen to start</div>
<iframe id="omnilab-embed" allow="camera; geolocation" hidden></iframe>
<button id="home-button" type="button" hidden>Home</button>
<div id="idle-modal" role="alertdialog" aria-labelledby="idle-title" hidden>
<p id="idle-title">Are you still there?</p>
<p>Returning home in <span id="idle-countdown"></span> seconds</p>
<button id="idle-stay" type="button">Stay</button>
<button id="idle-home" type="button">Return home</button>
</div>
<script>
const EXPERIENCE_ORIGIN = "https://play.lindenhall.example";
const TOUCHPOINT_URL = EXPERIENCE_ORIGIN + "/lindenhall-autumn-kiosk?c=a315&l=en";
const COUNTDOWN_SECONDS = 10;
const GRACE_MS = 30000; // après Stay, ignorer le signal pendant cette durée
const welcome = document.getElementById("welcome");
const frame = document.getElementById("omnilab-embed");
const modal = document.getElementById("idle-modal");
const countdown = document.getElementById("idle-countdown");
const homeButton = document.getElementById("home-button");
let inSession = false;
let countdownTimer = null;
let ignoreIdleUntil = 0;
function startSession(scannedValue) {
const who = scannedValue ? "&fci=" + encodeURIComponent(scannedValue) : "&login=0";
frame.src = TOUCHPOINT_URL + who;
frame.hidden = false;
homeButton.hidden = false;
welcome.hidden = true;
inSession = true;
ignoreIdleUntil = 0;
}
function endSession() {
clearInterval(countdownTimer);
modal.hidden = true;
frame.src = "about:blank";
frame.hidden = true;
homeButton.hidden = true;
welcome.hidden = false;
inSession = false;
}
function showIdleModal() {
let remaining = COUNTDOWN_SECONDS;
countdown.textContent = remaining;
modal.hidden = false;
countdownTimer = setInterval(() => {
remaining -= 1;
countdown.textContent = remaining;
if (remaining <= 0) endSession();
}, 1000);
}
function stay() {
clearInterval(countdownTimer);
modal.hidden = true;
// Les appuis sur cette fenêtre n'atteignent jamais l'expérience : son minuteur
// continue de tourner et renvoie le signal en quelques secondes. Laissez d'abord du temps au visiteur.
ignoreIdleUntil = Date.now() + GRACE_MS;
}
document.getElementById("idle-stay").addEventListener("click", stay);
document.getElementById("idle-home").addEventListener("click", endSession);
homeButton.addEventListener("click", endSession);
window.addEventListener("message", (event) => {
if (event.origin !== EXPERIENCE_ORIGIN) return;
if (!event.data || event.data.type !== "omnilab:idle") return;
if (!inSession || !modal.hidden || Date.now() < ignoreIdleUntil) return;
showIdleModal();
});
// La plupart des lecteurs USB tapent le code-barres, puis appuient sur Entrée.
let scanned = "";
document.addEventListener("keydown", (event) => {
if (inSession) return;
if (event.key === "Enter") {
startSession(scanned.trim());
scanned = "";
} else if (event.key.length === 1) {
scanned += event.key;
}
});
welcome.addEventListener("click", () => startSession(""));
</script>
</body>
</html>Ce que chaque partie permet d'éviter :
- La vérification de l'origine. Une application de borne qui réagit à tous les messages réagit aux messages de n'importe quelle page chargée dans l'iframe.
- La vérification
modal.hidden. Sans elle, chaque signal répété relance le compte à rebours, et la fenêtre n'expire jamais. - Le délai de grâce. Sans lui, la fenêtre revient dans les 10 secondes qui suivent un appui sur Stay.
about:blankau retour à l'accueil. L'expérience ne peut pas se décharger elle-même. Si la borne ne réagit pas au signal, il ne se passe rien.- Le bouton Home. Il a sa propre barre sous l'iframe, et ne couvre donc jamais l'expérience. Il met fin à la session de la même façon que le compte à rebours.
Recevoir le signal dans une WebView
Dans une WebView, l'expérience est la page de premier niveau : window.parent est donc la page elle-même. Le signal arrive sur la fenêtre de l'expérience. Injectez ce script dans chaque page que charge la WebView, pour transmettre le signal à votre app :
(function () {
if (window.__omnilabIdleBridge) return;
window.__omnilabIdleBridge = true;
function forward(message) {
const json = JSON.stringify(message);
if (window.ReactNativeWebView) {
window.ReactNativeWebView.postMessage(json); // React Native
} else if (window.webkit && window.webkit.messageHandlers && window.webkit.messageHandlers.omnilab) {
window.webkit.messageHandlers.omnilab.postMessage(json); // iOS WKWebView
} else if (window.OmnilabBridge) {
window.OmnilabBridge.postMessage(json); // Android WebView
}
}
window.addEventListener("message", (event) => {
if (event.source !== window || event.origin !== window.location.origin) return;
if (event.data && event.data.type === "omnilab:idle") forward(event.data);
});
})();
true;| Plateforme | Injecter le script avec | Recevoir le signal avec |
|---|---|---|
| React Native | La prop injectedJavaScript | onMessage, dans event.nativeEvent.data |
iOS WKWebView | Un WKUserScript en fin de document, frame principale uniquement | Un WKScriptMessageHandler ajouté sous le nom omnilab |
Android WebView | evaluateJavascript, dans onPageFinished | addJavascriptInterface sous le nom OmnilabBridge, avec une méthode @JavascriptInterface postMessage(String) |
Développez la fenêtre et le bouton Home en natif, avec les mêmes règles que la page de borne ci-dessus : un seul compte à rebours à la fois, un délai de grâce après Stay, et un bouton Return home. Pour mettre fin à la session, remplacez l'expérience par votre écran d'accueil. Démarrez la suivante en chargeant de nouveau l'adresse, avec l, puis fci ou login=0.
Ce que l'application de la borne gère aussi
- Les autorisations de l'appareil pour la caméra et la localisation, si l'expérience les utilise.
- Le matériel de scan et les autres périphériques.
- La journalisation et les diagnostics de support à distance de la borne elle-même.
- Tout accès API de serveur à serveur, depuis votre propre backend. Ne placez jamais d'identifiants client OmniLab dans la page de borne ni dans le bundle de la WebView.
Étapes suivantes
Gestion de l'inactivité
Réinitialisez automatiquement une borne quand un visiteur s'en va en cours d'expérience, pour que l'écran soit prêt pour la personne suivante.
Checklist de mise en place d'une borne
Menez un déploiement borne en trois étapes (architecture, tests et lancement) et sachez à qui signaler chaque type de problème.