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.

10 min de lecture

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

EnvironnementAdresse du script
Productionhttps://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 :

Conteneur + tag
<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-workshops ouvre la page d'accueil de la campagne.
  • https://www.lindenhall.example/promo?id=lindenhall-autumn-workshops?c=a315 ouvre 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 :

En-tête Content-Security-Policy
Content-Security-Policy: script-src 'self' https://cdn.21-digital.com; frame-src https://play.lindenhall.example

Conservez 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 :

Afficher l'expérience après une navigation côté client
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 :

loginStatusLe tag ajouteÀ chaque fois que votre page charge l'iframe
Non défini, ou toute valeur autre que la chaîne "True"login=0L'expérience démarre sans connexion, même pour un participant qui s'est connecté lors d'une visite précédente
"True"login=1L'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 :

Avant le snippet
<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.

OptionDéfautRôle
domainaucunL'hôte depuis lequel vos expériences sont diffusées, ici play.lindenhall.example. Obligatoire. Sans schéma, le tag utilise https.
targetIdaucunL'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
allowFullscreendésactivéDéfinissez-le sur true pour ajouter les attributs plein écran
sandboxAttributesnon définiAjoute un attribut sandbox avec la valeur donnée
stickyHeaderSelector#main-header, puis headerL'élément sous lequel les panneaux doivent rester. false désactive la détection.
topOffset0Pixels à laisser libres en haut quand aucun header n'est trouvé, ou que la détection est désactivée
scrollIntoViewOnNavigatetrueFait 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 :

Pointer le tag vers votre propre header
_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

MessageFormeEnvoyé quandVotre 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 viewportRé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

MessageFormeQuand l'envoyerEffet
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 panneauFerme 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'id de votre page, puis ajoute embedded=1, login, frameorigin et frameparam. 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 renvoie viewport quand 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-to par un saut, pas par une animation.
  • Répond ready-to-close-modal à chaque close-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.

Page parente écrite à la main
<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 :

  • frameorigin est 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 toujours id : définissez donc frameparam sur id, et n'utilisez id pour 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 que targetId correspond à l'id du conteneur.
  • _om_async.push is not a function : le script est déjà chargé. Appelez init comme dans Réinitialiser le tag dans une application monopage.
  • L'iframe reste à la hauteur de l'écran, avec sa propre barre de défilement : domain ne correspond pas exactement à l'hôte de l'iframe, donc le tag ignore ses messages.
  • Un spinner de chargement ne disparaît jamais : init s'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

Sur cette page