Développer la WebView

Chargez une expérience OmniLab dans une WebView React Native, iOS ou Android, avec les réglages essentiels.

4 min de lecture

Cette page s'adresse à votre développeur mobile. Vérifiez d'abord les exigences WebView puis, une fois le développement terminé, testez avec la checklist d'intégration mobile.

Garder la connexion dans la WebView

La plupart des apps envoient vers le navigateur du téléphone les liens qui quittent l'expérience. La connexion quitte elle aussi le domaine de l'expérience : un filtre qui ne connaît que ce domaine la bloque. Gardez ces hôtes dans la WebView :

HôteExemple
Votre domaine d'expérienceplay.lindenhall.example
L'étape de connexion : votre sous-domaine par défaut, suivi de .api.topage.co, ou de .api.uat.topage.co en Staginglindenhall.api.topage.co
Les pages de connexion de votre fournisseur d'identitéid.lindenhall.example

Pendant une connexion de test, journalisez chaque adresse que voit le filtre. Ajoutez tout autre hôte par lequel passe l'aller-retour, puis ouvrez tout le reste dans le navigateur.

React Native

npm install react-native-webview
OmniLab dans une WebView React Native
import React from "react";
import { Linking } from "react-native";
import { WebView } from "react-native-webview";
import type { ShouldStartLoadRequest } from "react-native-webview/lib/WebViewTypes";

const EXPERIENCE_URL = "https://play.lindenhall.example/lindenhall-autumn-workshops?c=a315";

// L'expérience, puis chaque hôte par lequel passe sa connexion.
const IN_APP_HOSTS = ["play.lindenhall.example", "lindenhall.api.topage.co", "id.lindenhall.example"];

type OmniLabScreenProps = {
  language: string;
  memberId?: string;
};

function hostOf(url: string): string {
  const match = /^https?:\/\/([^/?#:]+)/i.exec(url);
  return match ? match[1].toLowerCase() : "";
}

export default function OmniLabScreen({ language, memberId }: OmniLabScreenProps) {
  const uri =
    EXPERIENCE_URL +
    `&l=${encodeURIComponent(language)}` +
    (memberId ? `&fci=${encodeURIComponent(memberId)}` : "");

  const keepInApp = (request: ShouldStartLoadRequest): boolean => {
    // iOS signale les frames de la page, comme une vidéo : laissez-les se charger.
    if (request.isTopFrame === false) return true;
    // Les fichiers que la page crée elle-même, comme un fichier calendrier.
    if (/^(blob|data|about):/i.test(request.url)) return true;
    if (IN_APP_HOSTS.includes(hostOf(request.url))) return true;
    // Tout le reste, comme le site d'un sponsor ou les conditions, s'ouvre dans le navigateur.
    Linking.openURL(request.url).catch(() => {});
    return false;
  };

  return (
    <WebView
      source={{ uri }}
      style={{ flex: 1 }}
      geolocationEnabled
      allowsInlineMediaPlayback
      mediaPlaybackRequiresUserAction={false}
      mediaCapturePermissionGrantType="grantIfSameHostElsePrompt"
      onShouldStartLoadWithRequest={keepInApp}
    />
  );
}

Ce que font les réglages :

  • flex: 1 : sans ce réglage, la hauteur de la WebView tombe à zéro et rien ne s'affiche, ce qui passe pour un échec de chargement.
  • geolocationEnabled : active la localisation sur Android, où elle est désactivée par défaut. Les chasses au trésor et les vérifications de position en ont besoin.
  • allowsInlineMediaPlayback : permet à l'aperçu caméra d'un scan de QR code de s'afficher dans la page sur iOS.
  • mediaCapturePermissionGrantType : sur iOS 15 et versions ultérieures, l'expérience utilise la caméra sans que la page demande une seconde autorisation.
  • onShouldStartLoadWithRequest : applique la liste d'hôtes ci-dessus. Les liens externes s'ouvrent dans le navigateur, d'où le participant peut revenir.

La bibliothèque ouvre elle-même le sélecteur de fichiers du système, pour l'envoi de tickets de caisse et les champs photo.

iOS natif

Utilisez WKWebView :

  • Définissez allowsInlineMediaPlayback sur true dans sa configuration, pour que l'aperçu caméra d'un scan de QR code s'affiche dans la page.
  • Implémentez webView(_:requestMediaCapturePermissionFor:initiatedByFrame:type:decisionHandler:) pour accorder la caméra à votre domaine d'expérience. Sinon, WebKit ajoute sa propre demande par-dessus celle de l'app.
  • Dans webView(_:decidePolicyFor:decisionHandler:), autorisez les frames autres que la frame principale, ainsi que les hôtes ci-dessus. Ouvrez tout le reste avec UIApplication.shared.open, puis annulez.
  • Implémentez webView(_:createWebViewWith:for:windowFeatures:). L'expérience ouvre ses conditions et certains liens dans une nouvelle fenêtre, ce que WKWebView ignore sans cette méthode.

Android natif

Utilisez la WebView standard :

  • Activez javaScriptEnabled et domStorageEnabled dans ses réglages. Les deux sont désactivés par défaut.
  • Dans votre WebChromeClient, implémentez onPermissionRequest. Accordez la caméra après avoir vérifié l'autorisation d'exécution de l'app : la demande de la page et la permission Android sont deux verrous distincts.
  • Implémentez onShowFileChooser, et renvoyez le fichier choisi. Sans cela, l'envoi de tickets et les champs photo restent sans effet.
  • Implémentez onGeolocationPermissionsShowPrompt, et appelez callback.invoke(origin, true, false) une fois que l'app a la permission de localisation. Sans cela, les vérifications de position échouent.
  • Dans votre WebViewClient, appliquez la liste d'hôtes dans shouldOverrideUrlLoading. Ouvrez tout le reste avec un intent ACTION_VIEW.
  • Appelez setMediaPlaybackRequiresUserGesture(false) dans ses réglages, pour que les médias que l'expérience lance elle-même, comme l'aperçu caméra, puissent se lire.

Déclarer les permissions

FonctionnalitéiOS Info.plistManifeste Android
CaméraNSCameraUsageDescriptionandroid.permission.CAMERA
Photothèque, pour les envoisNSPhotoLibraryUsageDescriptionAucune pour le sélecteur du système
LocalisationNSLocationWhenInUseUsageDescriptionandroid.permission.ACCESS_FINE_LOCATION

Une description d'usage iOS manquante provoque la fermeture de l'app la première fois que la permission est demandée.

Enregistrer les fichiers

Le fichier calendrier ou le billet d'une réservation, et une photo que le participant enregistre, sont des fichiers que la page crée elle-même. La page propose chacun d'eux comme lien de téléchargement, et libère ce lien juste après l'appui. Une WebView n'enregistre pas un tel fichier d'elle-même, et un gestionnaire de téléchargement qui récupère le lien après coup n'obtient rien. Capturez plutôt le fichier dans la page :

Injecté dans la page de l'expérience par votre app
(function () {
  if (window.__omnilabDownloadBridge) return;
  window.__omnilabDownloadBridge = 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
    }
  }

  // Garde chaque fichier créé par la page jusqu'à ce qu'elle libère le lien, pour qu'un appui puisse encore le lire.
  const files = new Map();
  const createObjectURL = URL.createObjectURL.bind(URL);
  const revokeObjectURL = URL.revokeObjectURL.bind(URL);
  URL.createObjectURL = function (object) {
    const url = createObjectURL(object);
    if (object instanceof Blob) files.set(url, object);
    return url;
  };
  URL.revokeObjectURL = function (url) {
    files.delete(url);
    revokeObjectURL(url);
  };

  document.addEventListener("click", (event) => {
    const link = event.target instanceof Element ? event.target.closest("a[download]") : null;
    const file = link ? files.get(link.href) : null;
    if (!file) return;
    event.preventDefault();
    const reader = new FileReader();
    reader.onload = () =>
      forward({ type: "omnilab:download", filename: link.download, mimeType: file.type, dataUrl: reader.result });
    reader.readAsDataURL(file);
  }, true);
})();
true;
PlateformeInjecter le script et recevoir le fichier avecEnsuite
React NativeLa prop injectedJavaScript, et onMessage, dans event.nativeEvent.dataÉcrivez dataUrl dans un fichier nommé filename avec votre bibliothèque de système de fichiers, puis ouvrez la feuille de partage
iOS WKWebViewUn WKUserScript en fin de document, frame principale uniquement, et un WKScriptMessageHandler nommé omnilabDécodez dataUrl en Data, écrivez-le dans un fichier temporaire nommé filename, puis présentez un UIActivityViewController
Android WebViewevaluateJavascript dans onPageFinished, et addJavascriptInterface nommé OmnilabBridge, avec une méthode @JavascriptInterface postMessage(String)Décodez la partie Base64 de dataUrl, puis enregistrez-la avec MediaStore ou partagez-la avec un intent ACTION_SEND

Transmettre votre membre connecté

Si votre app sait qui est le participant, ajoutez fci à l'adresse. C'est la campagne qui détermine s'il accède ensuite à l'expérience sans écran de connexion : voir Ce que votre app doit ajouter.

Gardez les identifiants hors du bundle de l'app

Si votre app a aussi besoin d'un accès serveur à serveur à OmniLab, passez par votre propre backend. Tout ce qui est livré dans un bundle d'app peut en être extrait.

Étapes suivantes

Sur cette page