Démarrer

Détecter le pont

L’application injecte son script avant l’exécution de vos propres scripts, à chaque chargement d’une page de votre origine. window.mairies est donc en général déjà disponible quand votre code s’exécute.

Pour couvrir les cas limites, l’application émet aussi l’événement mairies:ready sur window dès que l’objet est en place. Une petite fonction couvre les deux cas :

function whenMairiesReady() {
  return new Promise((resolve) => {
    if (window.mairies) return resolve(window.mairies);
    window.addEventListener('mairies:ready', () => resolve(window.mairies), { once: true });
    // Hors application, l’événement n’arrive jamais.
    setTimeout(() => resolve(null), 1000);
  });
}

const mairies = await whenMairiesReady();
if (!mairies) {
  // Site ouvert dans un navigateur classique, ou WebApp avancée non activée.
}

window.mairies n’existe que si les trois conditions suivantes sont réunies :

• la page est ouverte depuis une carte lien de l’application iPhone ou Android ;
• la section « WebApp avancée » de cette carte est activée, avec au moins une fonction cochée ;
• la page est la page principale (pas une iframe) et son origine est exactement celle du lien.

L’objet est figé : il ne peut être ni modifié ni remplacé par un autre script de la page.

Prévoir un repli hors application

Votre site reste un site web ordinaire : il doit fonctionner dans un navigateur classique, où window.mairies n’existe pas. Testez donc la présence de l’objet, et celle de la fonction dont vous avez besoin, avant d’afficher un bouton qui en dépend :

function canUse(command) {
  return Boolean(window.mairies && window.mairies.commands.includes(command));
}

if (canUse('torch')) {
  document.querySelector('#lampe').hidden = false;
}

Quelques règles simples :

• N’affichez pas une commande qui ne fonctionnera pas : masquez le bouton plutôt que de le désactiver sans explication.
• Proposez une alternative quand elle existe : saisie manuelle d’un code si la caméra est refusée, formulaire de connexion habituel si auth n’est pas cochée.
• Ne déduisez pas la plateforme de l’agent utilisateur (navigator.userAgent) : lisez window.mairies.platform.

Premier appel

Toutes les méthodes renvoient une Promise. En cas d’échec, elle est rejetée avec une erreur qui porte un code (voir Codes d’erreur).

const mairies = await whenMairiesReady();

if (mairies && mairies.commands.includes('torch')) {
  try {
    const { available } = await mairies.torch.isAvailable();
    if (available) {
      const { on } = await mairies.torch.toggle();
      console.log(on ? 'Lampe allumée' : 'Lampe éteinte');
    }
  } catch (error) {
    console.warn('Appel refusé :', error.code);
  }
}

Pour vérifier l’installation, ouvrez votre page depuis l’application et affichez dans la page le contenu de window.mairies :

const m = window.mairies;
document.querySelector('#diagnostic').textContent = JSON.stringify(
  m ? { version: m.version, platform: m.platform, commands: m.commands } : null,
);
// Par exemple : {"version":1,"platform":"ios","commands":["torch","camera"]}

La suite : Torche, Caméra, Connexion dans le navigateur, ou l’exemple complet.