Référence du tag JavaScript
Installez le tag JavaScript, définissez ses options et gérez les messages entre votre page et une expérience intégrée.
Cette page s'adresse à votre développeur. Avec le tag, une seule page modèle peut afficher n'importe quelle expérience, désignée par l'adresse de la page elle-même.
La valeur à obtenir d'abord
Le snippet a besoin de l'hôte depuis lequel vos expériences sont diffusées. Pour un site sur www.lindenhall.example, c'est un sous-domaine comme play.lindenhall.example. Ce doit être un sous-domaine de votre site, sinon les participants ne peuvent pas rester connectés. Voir Domaine personnalisé.
Installer le tag
| Environnement | Adresse du script |
|---|---|
| Production | https://cdn.21-digital.com/omplayer.js |
| Staging (UAT) | https://cdn-uat.21-digital.com/omplayer.js |
Utilisez la Production. Ne chargez l'adresse de Staging que pour tester avec une expérience de Staging.
Placez le conteneur à l'endroit où l'expérience doit s'afficher, puis le snippet juste après :
<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 votre page qui détermine l'expérience chargée. La valeur de id est le chemin après l'hôte de l'expérience :
https://www.lindenhall.example/promo?id=lindenhall-autumn-workshopsouvre la page d'accueil de la campagne.https://www.lindenhall.example/promo?id=lindenhall-autumn-workshops?c=a315ouvre un point de contact.
Le tag lit id jusqu'au & ou au # suivant : un seul ? imbriqué fonctionne donc tel quel. Pour transmettre plusieurs paramètres imbriqués, encodez toute la valeur en URL : id=lindenhall-autumn-workshops%3Fc%3Da315%26l%3Den.
N'ajoutez pas embedded=1 vous-même. Le tag l'ajoute quand il construit l'iframe.
Ce dont le tag a besoin de votre page
Laissez le conteneur vide. Le tag ajoute son spinner de chargement et l'iframe après tout ce qui se trouve déjà dans #omnilab-container. Affichez l'élément vide, et ne laissez pas votre framework réafficher son contenu.
Ne définissez pas la hauteur de l'iframe en CSS. Le tag dimensionne l'iframe avec son attribut height, et toute propriété height en CSS l'emporte sur cet attribut. Définissez plutôt le style de l'iframe avec les options iframeStyle et iframeClass.
Autorisez les deux hôtes dans votre politique de sécurité de contenu. Si votre site envoie une politique, l'intégration est bloquée tant qu'elle n'autorise pas l'hôte du tag et l'hôte de l'expérience :
Content-Security-Policy: script-src 'self' https://cdn.21-digital.com; frame-src https://play.lindenhall.exampleConservez vos propres sources dans chaque directive. Le snippet est un script inline : ajoutez-lui donc le nonce de votre page, ou déplacez-le dans un fichier sur votre propre domaine. Si vous testez aussi avec Staging, autorisez également l'hôte du script de Staging et votre hôte d'expérience de Staging.
Le tag ajoute aussi un petit <style> inline pour son spinner de chargement, sans nonce. Un style-src sans 'unsafe-inline' le bloque et journalise une erreur. L'expérience se charge quand même, mais son emplacement reste vide jusqu'à ce qu'elle apparaisse. Ajoutez 'unsafe-inline' à style-src si vous voulez le spinner.
La politique de sécurité est la raison la plus fréquente pour laquelle une intégration qui fonctionnait sur une page de test échoue sur le vrai site. La page de test n'avait pas de politique ; le vrai site en a une.
Réinitialiser le tag dans une application monopage
Dans une application monopage, le script se charge une fois et reste chargé. Quand votre routeur réaffiche la page, avec un nouveau conteneur vide, appelez init vous-même. Cette fonction s'exécute correctement, que le script ait fini de se charger ou non :
function showLindenhallExperience() {
var options = {
domain: "play.lindenhall.example",
targetId: "omnilab-container",
queryParam: "id",
};
if (window._om_async && typeof window._om_async.init === "function") {
window._om_async.init(options);
} else {
window._om_async = window._om_async || [];
window._om_async.push(["init", options]);
}
}N'exécutez pas le snippet une seconde fois. Une fois le script chargé, _om_async est le tag lui-même, sans push : le snippet lève donc une erreur.
N'appelez init que sur un conteneur vide. Si l'iframe précédente est encore dans la page, le tag ajoute un spinner qui ne disparaît jamais. Le tag relit aussi id dans l'adresse : la nouvelle route doit donc le contenir.
Ce qui change après une réinitialisation : le tag indique toujours à la nouvelle iframe la place dont dispose un panneau, à chaque chargement de page à l'intérieur. Il ne le fait plus quand la fenêtre change de taille ou que le téléphone pivote, et chaque redimensionnement journalise une erreur dans la console. Un panneau ouvert après une rotation peut alors être dimensionné pour l'ancien écran, jusqu'à ce que le visiteur passe à une autre page. Un rechargement complet de la page corrige cela.
Statut de connexion
Le tag indique à l'expérience si votre propre site a connecté le visiteur. Il lit une variable globale, loginStatus, à son initialisation, et ajoute login à l'adresse de l'iframe :
loginStatus | Le tag ajoute | À chaque fois que votre page charge l'iframe |
|---|---|---|
Non défini, ou toute valeur autre que la chaîne "True" | login=0 | L'expérience démarre sans connexion, même pour un participant qui s'est connecté lors d'une visite précédente |
"True" | login=1 | L'expérience fait passer le visiteur par la connexion avant d'afficher quoi que ce soit |
Seule exception : au retour de la connexion, le participant reste connecté.
Définissez la variable avant le snippet, et seulement quand votre propre site a connecté le visiteur :
<script>
window.loginStatus = "True";
</script>Ce doit être la chaîne "True". Le booléen true équivaut à « non connecté ».
Options
Passez-les dans le même objet que domain et targetId.
| Option | Défaut | Rôle |
|---|---|---|
domain | aucun | L'hôte depuis lequel vos expériences sont diffusées, ici play.lindenhall.example. Obligatoire. Sans schéma, le tag utilise https. |
targetId | aucun | L'id du conteneur où va l'iframe. Obligatoire. |
queryParam | "id" | Le paramètre de l'adresse de votre page qui nomme l'expérience. Gardez id si les participants se connectent : le retour de la connexion utilise toujours id. |
width | "100%" | Largeur du conteneur et de l'iframe |
height | "100px" | Hauteur minimale du conteneur. La hauteur de l'iframe elle-même vient de l'écran et de l'expérience. |
iframeId | "omnilab-iframe" | id donné à l'iframe |
iframeClass | "" | Classes CSS supplémentaires sur l'iframe |
iframeStyle | "border: none;" | Style inline sur l'iframe |
allowFullscreen | désactivé | Définissez-le sur true pour ajouter les attributs plein écran |
sandboxAttributes | non défini | Ajoute un attribut sandbox avec la valeur donnée |
stickyHeaderSelector | #main-header, puis header | L'élément sous lequel les panneaux doivent rester. false désactive la détection. |
topOffset | 0 | Pixels à laisser libres en haut quand aucun header n'est trouvé, ou que la détection est désactivée |
scrollIntoViewOnNavigate | true | Fait remonter votre page jusqu'à l'embed quand le visiteur change de page à l'intérieur et que le haut de l'embed est au-dessus de l'écran. false ne touche pas au défilement. |
Headers sticky
Le tag écarte les panneaux d'un header fixé en haut de votre page. Il cherche l'élément dont l'id est main-header, puis le premier élément <header>. Il mesure le bord inférieur de cet élément : un header qui défile hors de l'écran n'est donc plus pris en compte. Il ne laisse jamais libre plus d'un tiers de l'écran.
Si votre header est un autre élément, indiquez-le. Remplacez l'appel push du snippet par celui-ci :
_om_async.push([
"init",
{
domain: "play.lindenhall.example",
targetId: "omnilab-container",
stickyHeaderSelector: "#site-nav",
},
]);Utilisez un sélecteur stable, comme un id ou un attribut data, pas une classe hachée qui change d'un build à l'autre. Si le sélecteur ne correspond à rien, ou si vous passez false, le tag laisse plutôt topOffset pixels libres.
Messages entre la page et l'expérience
Votre page et l'expérience communiquent par postMessage. Le tag gère tous les messages ci-dessous. Lisez la suite si vous écrivez la page parente vous-même, ou si vous devez en déboguer une.
L'expérience ne mène cet échange que si son adresse contient embedded=1. Sans lui, l'expérience n'envoie que resize, et les panneaux s'ouvrent au bord de l'iframe entière, souvent hors de l'écran.
Vérifiez l'origine. L'expérience envoie ses messages à n'importe quelle origine. N'agissez que sur les messages dont l'event.origin est exactement l'hôte de votre expérience, ici https://play.lindenhall.example. Envoyez vos réponses à cette même origine.
De l'expérience vers votre page
| Message | Forme | Envoyé quand | Votre page doit |
|---|---|---|---|
resize | { type: "resize", target: "body", data: { height } } | La hauteur de la page change : au plus une fois par frame d'animation, jamais deux fois de suite la même hauteur. Les jeux et les pages d'erreur ne l'envoient jamais. | Définir la hauteur de l'iframe à height pixels. Ignorer les valeurs inférieures à 100. |
request-viewport | { type: "request-viewport" } | L'expérience est prête à recevoir viewport | Répondre avec viewport |
open-modal | { type: "open-modal" } | Le premier panneau s'ouvre. Les panneaux imbriqués ne le répètent pas. | Rien d'obligatoire |
scroll-to | { type: "scroll-to", top, height } | Un panneau a été placé, et de nouveau si son espace change pendant qu'il est ouvert. top et height sont en pixels dans la page même de l'iframe. | Faire défiler pour que ce bloc se place au milieu de la zone visible, sous votre header |
close-modal | { type: "close-modal", source } | Le dernier panneau se ferme : il signifie donc toujours « entièrement fermé ». source vaut "closeButton", "backdrop" ou "escape". | Rien d'obligatoire |
De votre page vers l'expérience
| Message | Forme | Quand l'envoyer | Effet |
|---|---|---|---|
viewport | { type: "viewport", availableHeight } | Au chargement de l'iframe, en réponse à request-viewport, et quand votre fenêtre change de taille. Pas au défilement. | Définit la hauteur maximale d'un panneau : la hauteur visible de votre écran, moins votre header sticky. Ce doit être un nombre supérieur à 0. |
ready-to-close-modal | { type: "ready-to-close-modal", source } | Facultatif, quand votre propre interface ferme le panneau | Ferme le panneau du dessus |
Sans viewport, un panneau peut atteindre la hauteur de l'iframe entière.
Panneaux
Quand un visiteur ouvre un panneau, l'expérience le place près de son dernier appui, sans dépasser availableHeight. Elle envoie open-modal, puis scroll-to avec la position du panneau, et votre page défile pour le centrer. Quand le dernier panneau se ferme, elle envoie close-modal. Rien ne défile en sens inverse à la fermeture.
Laissez le défilement de votre page actif pendant qu'un panneau est ouvert. Le panneau est fixé dans l'iframe : il se déplace donc avec votre page.
Ce que le tag fait pour vous
- Construit l'adresse de l'iframe à partir de l'
idde votre page, puis ajouteembedded=1,login,frameoriginetframeparam. Les deux derniers ramènent le visiteur sur votre page après la connexion. - N'accepte les messages que de
domain, et n'envoie qu'à lui. - À chaque chargement de page dans l'iframe, règle la hauteur de l'iframe sur la hauteur visible de votre écran, moins le header. Il envoie ensuite
viewport. - Applique chaque
resize, en ignorant les hauteurs inférieures à 100 et les changements de 2 pixels ou moins. - Répond à
request-viewport, et renvoieviewportquand la fenêtre, l'orientation ou la zone visible change. Après une réinitialisation dans une application monopage, il cesse de le renvoyer : voir Réinitialiser le tag dans une application monopage. - Traite
scroll-topar un saut, pas par une animation. - Répond
ready-to-close-modalà chaqueclose-modal. - Fait défiler jusqu'à l'embed quand le visiteur change de page à l'intérieur : voir
scrollIntoViewOnNavigate.
Une page parente écrite à la main
Cette page fait ce que fait le tag pour le dimensionnement, les panneaux et le retour de la connexion. Son iframe peut en plus utiliser la caméra et la localisation, ce que celle du tag ne peut pas. Remplacez l'adresse par celle de votre expérience.
<iframe
id="omnilab-embed"
allow="camera; geolocation"
style="width: 100%; border: none"
></iframe>
<script>
const EXPERIENCE_ORIGIN = "https://play.lindenhall.example";
const EXPERIENCE_PATH = "lindenhall-autumn-workshops?c=a315";
const frame = document.getElementById("omnilab-embed");
// Espace qu'occupe un header sticky en haut de l'écran.
function headerOffset() {
const header = document.querySelector("header");
const bottom = header ? header.getBoundingClientRect().bottom : 0;
return Math.min(Math.max(0, bottom), Math.floor(window.innerHeight / 3));
}
// Hauteur que le visiteur voit sous le header.
function availableHeight() {
const visible = window.visualViewport ? window.visualViewport.height : window.innerHeight;
return Math.max(0, visible - headerOffset());
}
function sendViewport() {
frame.contentWindow.postMessage(
{ type: "viewport", availableHeight: availableHeight() },
EXPERIENCE_ORIGIN
);
}
// À chaque chargement de page dans l'iframe : partir de la hauteur visible, puis indiquer la place disponible.
frame.addEventListener("load", () => {
frame.style.height = availableHeight() + "px";
sendViewport();
});
window.addEventListener("resize", sendViewport);
if (window.visualViewport) window.visualViewport.addEventListener("resize", sendViewport);
window.addEventListener("message", (event) => {
if (event.origin !== EXPERIENCE_ORIGIN) return;
const msg = event.data;
if (!msg || typeof msg !== "object") return;
if (msg.type === "resize" && msg.target === "body") {
const height = msg.data && msg.data.height;
if (typeof height !== "number" || height < 100) return;
if (Math.abs(height - frame.getBoundingClientRect().height) <= 2) return;
frame.style.height = height + "px";
} else if (msg.type === "request-viewport") {
sendViewport();
} else if (msg.type === "scroll-to") {
const frameTop = frame.getBoundingClientRect().top + window.scrollY;
const room = Math.max(0, availableHeight() - msg.height);
window.scrollTo(0, Math.max(0, Math.round(frameTop + msg.top - headerOffset() - room / 2)));
}
});
// Au retour de la connexion, l'adresse de cette page porte l'expérience dans `id`.
const returnedPath = new URLSearchParams(window.location.search).get("id");
const src = new URL(EXPERIENCE_ORIGIN + "/" + (returnedPath || EXPERIENCE_PATH));
src.searchParams.set("embedded", "1");
src.searchParams.set("frameorigin", window.location.href);
src.searchParams.set("frameparam", "id");
frame.src = src.toString();
</script>Comment fonctionne le retour de la connexion :
frameoriginest l'adresse complète de votre page. La connexion y renvoie le visiteur, en conservant les autres paramètres de votre page.- L'expérience où il se trouvait, avec ses paramètres, revient dans
id, encodée en URL. Elle utilise toujoursid: définissez doncframeparamsurid, et n'utilisezidpour rien d'autre sur la page. - Votre page reconstruit l'iframe à partir de
id, comme le font les dernières lignes ci-dessus. Sans elles, l'iframe rouvre votre adresse par défaut au lieu de celle depuis laquelle le visiteur s'est connecté.
En cas de blocage
- Rien n'apparaît, et la console n'affiche aucune erreur : vérifiez que l'adresse de votre page contient
id, et quetargetIdcorrespond à l'iddu conteneur. _om_async.push is not a function: le script est déjà chargé. Appelezinitcomme dans Réinitialiser le tag dans une application monopage.- L'iframe reste à la hauteur de l'écran, avec sa propre barre de défilement :
domainne correspond pas exactement à l'hôte de l'iframe, donc le tag ignore ses messages. - Un spinner de chargement ne disparaît jamais :
inits'est exécuté alors que l'iframe précédente était encore dans la page. Videz d'abord le conteneur. - La console signale un script ou une iframe bloqués : il manque un hôte dans votre politique de sécurité de contenu. Voir Ce dont le tag a besoin de votre page.
- La console signale un style inline bloqué : c'est le spinner de chargement du tag. Voir Ce dont le tag a besoin de votre page.
- Les panneaux n'ont pas la bonne hauteur après une rotation du téléphone, dans une application monopage : le tag a été réinitialisé. Voir Réinitialiser le tag dans une application monopage.
Étapes suivantes
Ce que votre page doit gérer
Ce dont votre page est responsable une fois une expérience intégrée : hauteur, panneaux, headers, connexion, politique de sécurité et permissions.
Checklist d'intégration à un site web
Testez une expérience intégrée sur une vraie page avant le lancement, et sachez à qui signaler chaque type de problème.