WebApp avancée

Principe

Quand une commune ajoute à son application une carte lien vers votre site, celui-ci s’ouvre dans l’application, dans une vue web intégrée. La WebApp avancée permet à cette page d’utiliser certaines fonctions du téléphone.

1. Un agent de la commune configure dans le backoffice une carte lien qui pointe vers votre site, par exemple https://services.exemple.fr/.

2. Dans les réglages de cette carte, il active la section « WebApp avancée » et coche les fonctions qu’il autorise.

3. Quand un habitant ouvre le lien dans l’application, celle-ci injecte automatiquement un objet JavaScript window.mairies dans votre page. Vous n’avez aucun fichier à inclure.

4. À chaque appel, l’application vérifie l’origine de la page, la frame appelante et la fonction demandée. Elle n’exécute l’action que si tout est conforme.

En dehors de l’application (navigateur classique, version web de l’application de la commune), window.mairies n’existe pas : prévoyez toujours un comportement de repli. Voir Démarrer.

Prérequis

Exigence	Détail
HTTPS obligatoire	L’adresse du lien doit commencer par https://. En http://, aucune fonction n’est disponible, et le backoffice refuse d’activer la section.
Origine exacte	Seule l’origine du lien configuré (https://hôte[:port]) est autorisée. Les sous-domaines ne le sont pas : https://app.exemple.fr et https://exemple.fr sont deux origines différentes.
Page principale uniquement	Une iframe, même servie par votre propre domaine, n’a pas accès à window.mairies.
Navigation hors domaine	Si l’utilisateur quitte votre origine (redirection, lien externe), la page affichée n’a plus accès au pont. Il redevient disponible au retour sur votre origine.

Seul le chemin de l’adresse peut varier : si le lien pointe vers https://exemple.fr/services/, toutes les pages de https://exemple.fr ont accès aux fonctions cochées.

Activer la WebApp avancée dans le backoffice

L’activation se fait par un agent de la commune, dans le backoffice. Transmettez-lui l’adresse exacte de votre site et la liste des fonctions dont vous avez besoin.

1. Dans l’écran « Apparence », onglet « Mise en page », ouvrir la carte lien (ou en ajouter une).

2. Vérifier que l’adresse commence par https://.

3. Activer « WebApp avancée ».

4. Sous « Fonctions autorisées », cocher les fonctions nécessaires.

5. Valider la carte (« Enregistrer », ou « Ajouter le lien » pour une nouvelle carte), puis cliquer sur « Enregistrer » dans l’écran « Apparence » et confirmer avec « Publier ».

Sous les cases, l’écran rappelle l’origine autorisée : « Utilisables uniquement depuis https://… ». Une section activée sans aucune case cochée est désactivée à l’enregistrement.

Capture à venirdeveloppeurs/webapp-avancee/activer-la-webapp-avancee

La procédure complète côté commune est décrite dans Référence des blocs et cartes.

Fonctions disponibles

Case dans le backoffice	Identifiant	Ce que votre page peut faire	Page
« Torche »	torch	Allumer, éteindre ou basculer la lampe du téléphone.	Torche
« Caméra »	camera	Accéder à la caméra avec l’API web standard getUserMedia. L’utilisateur doit aussi l’accepter sur son téléphone.	Caméra
« Connexion dans le navigateur »	auth	Ouvrir votre page de connexion dans le navigateur du téléphone, où passkeys et mots de passe enregistrés fonctionnent, puis revenir dans l’application.	Connexion dans le navigateur

L’identifiant est celui que votre page retrouve dans window.mairies.commands.

Compatibilité iOS et Android

La WebApp avancée fonctionne dans les applications mairies.net pour iPhone et pour Android. L’API est la même sur les deux plateformes ; window.mairies.platform vaut 'ios' ou 'android'.

Les différences à connaître :

• Moteur web : sur iPhone, la page s’affiche dans une vue WebKit (WKWebView) ; sur Android, dans la WebView du système (« Android System WebView »). Sur Android, une WebView trop ancienne ne prend pas en charge le pont : window.mairies est alors absent. La caméra, elle, reste utilisable.
• Torche pendant un flux caméra : le comportement diffère. Voir Torche pendant un flux caméra.
• Connexion dans le navigateur : la page s’ouvre dans une feuille Safari sur iPhone, dans un onglet du navigateur par défaut (Chrome, par exemple), ouvert par-dessus l’application, sur Android.
• Version web : dans la version web de l’application de la commune, ouverte dans un navigateur, votre site s’ouvre comme un lien ordinaire. window.mairies n’y existe pas.