L'API iFrame · Aide de Measure Map Online

Affichez l'un de vos projets sous forme de carte en direct sur votre propre site web, avec les unités, le style de carte et le thème qui conviennent à votre site.

L'API iFrame place la carte d'un projet sur votre propre page web. Les visiteurs voient la carte satellite avec vos mesures et peuvent s'y déplacer, sans compte et sans quitter votre site. Vous choisissez le projet, les unités, le style de carte et le thème de couleurs.

Avant de commencer#

Une clé d'API de production avec l'accès Cartes intégrées. Voir les clés d'API.
Un projet que les visiteurs peuvent voir. Réglez son niveau d'accès sur Affichage uniquement ou Public. Un projet Privé ne s'ouvre pas pour les visiteurs sans compte. Voir quels projets peuvent être intégrés.
Si vous le souhaitez, des restrictions de site web sur la clé, pour que l'intégration ne fonctionne que sur vos propres sites. Voir les clés d'API.

Générer le code d'intégration#

Développeur > Intégrer une carte génère le code pour vous avec votre clé de production : choisissez le projet, le thème, les unités, le type de carte et la taille, vérifiez l'Aperçu en direct et copiez le Code d’intégration. Si le projet est privé, la section le signale et propose Passer en « Affichage uniquement ». Voir obtenir le code d'intégration pour chaque étape.

Intégrer une carte avec un projet choisi et l'aperçu en direct

Le code contient votre clé : il fonctionne donc tant que vous ne remplacez pas la clé. La section vous avertit quand la clé peut faire plus que Cartes intégrées, puisque n'importe qui peut la lire dans le code source de votre page, et quand la clé n'a aucune restriction de site web. Seul l'Aperçu en direct utilise un jeton de courte durée. Voir clé ou jeton.

L'adresse d'intégration#

Une intégration est un <iframe> dont l'adresse commence par https://app.measuremaponline.com/iframe_api, suivie de ces paramètres :

Paramètre	Obligatoire	Valeurs
`pid`	obligatoire	L'identifiant du projet : la partie qui suit `/p/` dans l'adresse du projet dans l'application.
`key`	`key` ou `token`	Votre clé d'API.
`token`	`key` ou `token`	Un jeton fourni par votre serveur (voir plus bas).
`ms`	facultatif	Unités : `metric` ou `imperial`. Sans ce paramètre, les visiteurs situés aux États-Unis voient les unités impériales et tous les autres les unités métriques.
`maptype`	facultatif	`satellite` (par défaut), `map`, `hybrid` ou `terrain`.
`theme`	facultatif	`auto` (par défaut : suit le réglage système du visiteur), `light` ou `dark`.

Un exemple minimal#

<iframe src="https://app.measuremaponline.com/iframe_api?pid=YOUR_PROJECT_ID&key=YOUR_API_KEY&maptype=satellite&theme=auto"
  title="YOUR_PROJECT_NAME" width="500" height="500" style="border:0" allow="fullscreen"></iframe>

Remplacez YOUR_PROJECT_ID, YOUR_API_KEY et YOUR_PROJECT_NAME (les lecteurs d'écran lisent le title à voix haute), et réglez la largeur et la hauteur selon votre page.

Le code d'intégration avec son bouton de copie

Clé ou jeton#

Avec key, comme dans le code que donne la section Intégrer une carte, l'intégration fonctionne tant que la clé fonctionne, sur les sites web que ses restrictions autorisent. Votre clé est alors visible dans le code source de votre page, donc :

utilisez une clé qui n'a que l'accès Cartes intégrées ;
limitez-la à vos propres sites web ;
quand vous remplacez la clé, mettez à jour vos pages dans les 24 heures pendant lesquelles l'ancienne clé continue de fonctionner.

Avec token, la clé reste sur votre serveur. Cela convient aux intégrations que votre propre serveur écrit dans la page à chaque visite : avant d'afficher la page, il demande un jeton à l'API REST et le place dans l'adresse de l'iframe :

POST https://api.measuremaponline.com/api/v2/auth/iframe/token, avec votre clé dans l'en-tête Authorization, renvoie un token valable 60 minutes ;
POST https://api.measuremaponline.com/api/v2/auth/token fait de même et accepte une durée duration en secondes, jusqu'à 24 heures. Sa réponse indique quand le jeton expire.

Votre compte peut obtenir jusqu'à 600 jetons par heure. Utilisez une clé de production : les intégrations n'affichent que des projets de production, donc un jeton créé avec une clé de bac à sable n'ouvre aucune carte. Voir la référence de l'API.

Ce que peuvent faire les visiteurs#

Les visiteurs peuvent déplacer la carte, zoomer et lire les mesures de vos formes. Ils ne peuvent rien modifier : la modification est désactivée dans une intégration, quel que soit le niveau d'accès du projet. La seule exception est un projet Open Guest avec l'offre Open Guest, où les visiteurs mesurent eux-mêmes.

Quand la carte n'apparaît pas#

Vérifiez, dans cet ordre :

L'adresse contient un token qui a expiré. Les jetons durent 60 minutes, sauf si votre serveur a demandé une durée plus longue. Copiez à nouveau le code depuis Intégrer une carte, qui utilise votre clé, ou faites obtenir par votre serveur un nouveau jeton à chaque visite (voir plus haut).
Le projet est privé. Réglez-le sur Affichage uniquement ou Public, ou appuyez sur Passer en « Affichage uniquement » dans Intégrer une carte.
Le site web n'est pas autorisé. Si la clé a des restrictions de site web, la page qui affiche l'intégration doit faire partie de la liste. Certains navigateurs et sites masquent la page sur laquelle se trouve une intégration ; avec des restrictions définies, une telle intégration est refusée.
La clé a été remplacée. Une ancienne clé s'arrête 24 heures après la création d'une nouvelle, ou immédiatement si elle a été révoquée.
La clé est une clé de bac à sable. Les intégrations ne fonctionnent qu'avec des clés et des projets de production.
L'abonnement n'est pas actif, ou l'accès à l'API a été suspendu : la section Clés d’API l'indique.