Développer la WebView
Chargez une expérience OmniLab dans une WebView React Native, iOS ou Android, avec les réglages essentiels.
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ôte | Exemple |
|---|---|
| Votre domaine d'expérience | play.lindenhall.example |
L'étape de connexion : votre sous-domaine par défaut, suivi de .api.topage.co, ou de .api.uat.topage.co en Staging | lindenhall.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-webviewimport 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
allowsInlineMediaPlaybacksurtruedans 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 avecUIApplication.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 queWKWebViewignore sans cette méthode.
Android natif
Utilisez la WebView standard :
- Activez
javaScriptEnabledetdomStorageEnableddans ses réglages. Les deux sont désactivés par défaut. - Dans votre
WebChromeClient, implémentezonPermissionRequest. 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 appelezcallback.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 dansshouldOverrideUrlLoading. Ouvrez tout le reste avec un intentACTION_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.plist | Manifeste Android |
|---|---|---|
| Caméra | NSCameraUsageDescription | android.permission.CAMERA |
| Photothèque, pour les envois | NSPhotoLibraryUsageDescription | Aucune pour le sélecteur du système |
| Localisation | NSLocationWhenInUseUsageDescription | android.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 :
(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;| Plateforme | Injecter le script et recevoir le fichier avec | Ensuite |
|---|---|---|
| React Native | La 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 WKWebView | Un WKUserScript en fin de document, frame principale uniquement, et un WKScriptMessageHandler nommé omnilab | Décodez dataUrl en Data, écrivez-le dans un fichier temporaire nommé filename, puis présentez un UIActivityViewController |
Android WebView | evaluateJavascript 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.