Intégration embarquée et WebView

Ce guide couvre l'implémentation technique de tous les modes de diffusion embarquée d'OmniLab : iframe manuel, tag JavaScript player, WebView native (React Native et autres plateformes), et délégation de domaine personnalisé via DNS.

Consultez les aperçus orientés métier :

• Intégration par iframe
• Intégration WebView
• Délégation de domaine personnalisé

URLs prêtes pour l'intégration

Tous les modes de diffusion embarquée commencent à partir des mêmes patterns d'URL OmniLab :

Ajoutez toujours embedded=1 lors du chargement dans un iframe ou une WebView. Ce flag indique à OmniLab de fonctionner dans un contexte embarqué et adapte le layout et la navigation en conséquence.

Iframe manuel

Exemple minimal

<iframe
  id="omnilab-embed"
  src="https://experience.example.com/<lien-public-de-la-campagne>?c=<touchpoint-id>&embedded=1"
  title="Campagne OmniLab"
  loading="lazy"
  allow="camera; microphone; geolocation"
  style="width:100%;min-height:900px;border:0;overflow:hidden"
></iframe>

Adaptez l'attribut allow aux permissions requises par l'expérience. La caméra, le microphone et la géolocalisation ne sont nécessaires que si l'expérience utilise le scan, la capture média ou des parcours basés sur la localisation.

Redimensionnement automatique de la hauteur

Les pages OmniLab envoient des événements de redimensionnement via postMessage. Écoutez-les sur la page parente pour que la hauteur de l'iframe suive le contenu au lieu d'afficher une barre de défilement interne.

<script>
  window.addEventListener("message", (event) => {
    const data = event.data;

    if (data?.type !== "resize" || data?.target !== "body") return;

    const iframe = document.querySelector("#omnilab-embed");
    if (iframe && typeof data?.data?.height === "number") {
      iframe.style.height = data.data.height + "px";
    }
  });
</script>

Autres événements postMessage

OmniLab peut également émettre des événements liés au cycle de vie des modales que votre wrapper peut intercepter :

Pour enregistrer tous les messages pendant le développement :

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

Tag JavaScript player

Utilisez le tag JavaScript player OmniLab lorsqu'une seule page hôte doit charger différentes campagnes selon l'URL courante.

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

Avec cette configuration, l'URL de la page hôte détermine quelle expérience OmniLab se charge :

• Campagne simple : https://www.example.com/promo?id=summer-campaign
• Avec point de contact : https://www.example.com/promo?id=summer-campaign%3Fc%3D<touchpoint-id>%26embedded%3D1

La valeur dans id est le chemin après le domaine OmniLab. Encodez toute query string imbriquée avant de publier le lien. Si votre déploiement utilise une URL de script spécifique, utilisez-la à la place de l'espace réservé ci-dessus.

WebView React Native

Installation

npm install react-native-webview

Exemple minimal

import React from "react";
import { WebView } from "react-native-webview";

export default function OmniLabWebView() {
  return (
    <WebView
      source={{
        uri: "https://experience.example.com/<lien-public-de-la-campagne>?c=<touchpoint-id>&embedded=1",
      }}
      style={{ flex: 1 }}
      javaScriptEnabled
    />
  );
}

Utilisez une URL de page d'accueil de campagne lorsque l'application doit afficher plusieurs expériences, ou une URL directe de point de contact pour lancer immédiatement une expérience précise.

Exigences React Native

• Activez JavaScript (javaScriptEnabled={true}).
• Accordez les permissions caméra, microphone, géolocalisation et fichiers lorsque l'expérience en a besoin.
• Utilisez un conteneur plein écran ou bord à bord (flex: 1).
• Si l'application hôte doit réagir aux événements OmniLab, confirmez que le bridge de la WebView prend en charge postMessage.
• Testez le comportement du clavier virtuel lorsque l'expérience contient des formulaires ou des étapes de connexion.

Conseils pour iOS natif et Android natif

• Utilisez le composant WebView standard de la plateforme ou une bibliothèque wrapper maintenue.
• Activez JavaScript.
• Transmettez les demandes de permissions (caméra, microphone, géolocalisation) à la WebView.
• Testez les modes portrait et paysage sur des appareils réels.
• Vérifiez que le passage en arrière-plan, la reprise et la perte réseau ne cassent pas le parcours participant.
• Si le wrapper doit réagir aux événements postMessage, validez le bridge en staging avant de livrer.

Délégation de domaine personnalisé (configuration DNS)

Vue d'ensemble

Un domaine personnalisé délégué permet aux expériences OmniLab de fonctionner sous votre propre sous-domaine de marque (par exemple experience.example.com) au lieu du domaine hébergé par défaut d'OmniLab.

Enregistrement DNS à créer

Votre équipe DNS crée un enregistrement CNAME pointant le sous-domaine choisi vers le point de terminaison OmniLab :

Si votre fournisseur DNS ne prend pas en charge le CNAME à l'apex (domaine racine), utilisez un sous-domaine comme experience.example.com plutôt que de tenter de déléguer example.com lui-même.

Paramètres TTL

Définissez le TTL (durée de vie) de l'enregistrement DNS à une valeur basse (300–600 secondes) avant le basculement pour accélérer la propagation si vous devez effectuer un retour arrière. Une fois le domaine stable, vous pouvez augmenter le TTL.

Certificat SSL

OmniLab provisionne automatiquement un certificat SSL une fois l'enregistrement DNS vérifié. Comptez jusqu'à 15–30 minutes après la propagation DNS pour que le certificat soit actif. Pendant cette fenêtre, les navigateurs peuvent afficher un avertissement de certificat temporaire.

Délai de propagation

Les modifications DNS peuvent prendre jusqu'à 48 heures pour se propager globalement, selon votre fournisseur et le TTL existant sur l'enregistrement. Planifiez la délégation de domaine bien avant votre date de mise en production.

Modèle d'intégration typique

Checklist avant mise en ligne

• Sous-domaine personnalisé validé et enregistrement DNS créé.
• Propagation DNS vérifiée (utilisez un outil de vérification DNS).
• Certificat SSL actif (aucun avertissement de certificat dans le navigateur).
• URL OmniLab autonome fonctionnelle sur le nouveau nom d'hôte.
• Page intégrée testée : layout, permissions, cookies, redirections.
• QR codes et emplacements média existants mis à jour vers le nouveau nom d'hôte.

Bonnes pratiques de diffusion

• Laissez l'iframe occuper toute la largeur disponible ; évitez une largeur desktop étroite fixe.
• Démarrez avec une hauteur minimale généreuse (min-height: 900px), puis laissez l'écouteur de redimensionnement définir la hauteur finale.
• Testez les étapes de connexion, les permissions caméra, les redirections et la mise en page mobile directement dans la vraie page hôte.
• Si la page hôte utilise des en-têtes sticky ou des conteneurs contraints, testez les points de contact qui ouvrent des tiroirs, des formulaires, des claviers ou des demandes caméra.
• Gardez les secrets et tokens API sur votre backend — jamais dans la page borne ou le bundle WebView.

Pour aller plus loin