Intégrer une carte interactive à un site web

Vous pouvez intégrer une expérience cartographique interactive à un site web au moyen d’une iframe directe, d’un composant web réutilisable ou d’un SDK JavaScript connecté à une carte en direct. Utilisez une iframe pour une carte publiée autonome, un composant web pour un code HTML simple reposant sur une couche maintenue, et un SDK lorsque la page hôte doit contrôler la caméra, le cycle de vie ou les actions du produit. Une intégration en production exige également des dimensions définies, des restrictions de domaine, l’accessibilité, du texte indexable et une analyse des actions.

Les sections suivantes couvrent le choix de la méthode, la configuration de Kaleidr Viewer, les conteneurs adaptatifs, la sécurité, l’accessibilité, le SEO et les erreurs courantes. Pour relier une conversation à un moteur de rendu en direct, consultez Comment ajouter un chat IA à une carte. Pour la catégorie SDK, consultez Qu’est-ce qu’un SDK de cartographie IA ?.

Principes essentiels de l’intégration

• La méthode d’abord : Choisissez une iframe, un composant web, un SDK ou une bibliothèque cartographique native selon le niveau de contrôle requis par la page hôte, et non selon la longueur de l’exemple de code.
• Réservez la hauteur : Définissez explicitement la hauteur du conteneur avant le chargement pour éviter son effondrement et les décalages de mise en page.
• Viewer publié : Kaleidr Viewer utilise product="viewer" et un identifiant de partage ; l’accès dépend du lien partagé et des domaines autorisés par l’éditeur.
• Du texte hors du canevas : Titres, résumés et listes de lieux rendent la page utile aux utilisateurs du clavier, aux technologies d’assistance et aux moteurs de recherche.
• Mesurez les tâches : Suivez les chargements, sélections, itinéraires et conversions, pas seulement les affichages de la carte.

Comment intégrer une expérience cartographique interactive ?

Ce guide crée une section cartographique adaptative pour un site marketing, un guide de destination, une page immobilière, un localisateur de magasins, un article ou un produit logiciel. L’expérience finale comprend une carte interactive publiée, un conteneur fonctionnel sur ordinateur et mobile, un titre clair et un résumé textuel hors de la carte, un contrôle facultatif de la caméra depuis la page hôte, des restrictions de domaine ou d’identifiants, des états de chargement et d’échec, des alternatives accessibles aux informations uniquement cartographiques et des événements pour mesurer l’engagement. Les exemples utilisent Kaleidr Viewer, qui permet d’intégrer une carte publiée avec un chargeur et un élément personnalisé. Le même cadre de décision s’applique à une iframe de fournisseur, un composant web cartographique ou une implémentation personnalisée avec Mapbox, Google Maps, MapLibre ou Leaflet.

Comment choisir la bonne méthode d’intégration ?

La première décision est de savoir combien de contrôle le site Web de l'hôte a besoin.Une carte publiée sur une page de contenu n'a généralement pas besoin de la même architecture qu'une carte dans un flux de travail SaaS, alors évitez de choisir la méthode la plus complexe par défaut.

Utilisez un iframe direct lorsque la carte est autonome, la page hôte n'a besoin que de l'afficher, et un minimum de travail d'ingénierie est la priorité.Le HTML iframe élément crée un contexte de navigation intégré séparé, l’isolement utile, mais un autre environnement documentaire avec ses propres ressources et ses considérations d’accessibilité.Utilisez un composant Web lorsque l'équipe veut un élément HTML déclaratif, les attributs tels que l'ID de carte ou la caméra sont suffisants et le fournisseur maintient l'implémentation interne; éléments personnalisés peut cacher le chargement et la messagerie derrière un contrat public stable.Utilisez un SDK JavaScript lorsque l'hôte doit conserver une poignée, mettre à jour la caméra ou le thème, détruire la carte sur les changements de route, joindre à un rendu en direct ou coordonner l'authentification du navigateur, les événements ou les flux de travail d'IA.

Comment fonctionne l’intégration de Kaleidr Viewer ?

Kaleidr Viewer intègre une carte Kaleidr publiée à l’aide de son identifiant de partage. Viewer gère sa propre carte et s’exécute à travers une frontière iframe dans le composant <kaleidr-map> ; la page hôte peut contrôler les comportements pris en charge au moyen de la référence du SDK et de l’interface de messagerie documentée. Le contrat actuel présente quatre propriétés importantes : product="viewer" sélectionne Viewer pour la carte publiée ; share-id identifie cette carte ; l’accès dépend du lien de partage et ne nécessite pas de clé API ; les domaines autorisés par l’éditeur continuent de s’appliquer. Viewer se distingue de Kaleidr Chat : Viewer gère sa carte, tandis que Chat peut se connecter à une instance active de Mapbox, Google Maps, MapLibre ou Leaflet déjà présente dans l’application hôte.

Chargez une seule fois le chargeur versionné depuis https://cdn.kaleidr.com/embed/v1/kaleidr.js avant de monter un produit. Il définit <kaleidr-map>, installe window.Kaleidr, puis charge à la demande le paquet du produit sélectionné. L’intégration minimale d’une carte publiée place l’élément personnalisé avec une hauteur explicite :

<kaleidr-map
  product="viewer"
  share-id="abcd1234"
  style="display:block; height:520px;">
</kaleidr-map>

L’exemple suit le guide de démarrage rapide, la référence de <kaleidr-map> et la documentation d’intégration de Viewer actuels. Remplacez abcd1234 par l’identifiant de partage de la carte publiée. La carte doit être publiée et autorisée à s’afficher sur le domaine hôte. Préférez le composant documenté à la construction d’une URL interne de Viewer qui ne fait pas partie du contrat public.

Comment créer une page cartographique adaptative et accessible ?

Une carte intégrée a besoin d'une hauteur explicite.Sans un seul, le conteneur peut s'effondrer, produire une mise en page instable ou se rabattre sur un défaut spécifique au fournisseur.Enveloppez l'élément dans une coque qui réserve de l'espace avant que la carte ne se charge - pleine largeur, une hauteur minimale et souvent un rapport d'aspect 16:9 sur le bureau avec un minimum fixe plus élevé sur les téléphones étroits.La réservation d'espace réduit le mouvement inattendu de l'agencement; les intégrations sans dimensions définies sont une cause fréquente de déplacement cumulatif (web.dev CLS guidance).Testez la carte réelle plutôt que de vous fier uniquement au rapport d'aspect: une carte à écran large peu profonde fonctionne souvent sur le bureau, mais devient difficile à utiliser sur un téléphone.

L'élément Viewer observe center, zoom, pitch, bearing, et theme lorsque soutenu; center utilise la longitude, l'ordre de la latitude.Choisissez la caméra d’ouverture pour que le but de la carte soit clair – quartier, développement et transit, ou une vue nationale plus large avec une recherche ou un filtre évident.Lorsque la page hôte a besoin d'une poignée, montez avec l'API impérative après la présence du chargeur:

const viewer = Kaleidr.mount("#featured-map", {
  product: "viewer",
  shareId: "abcd1234",
  center: [-0.12, 51.5],
  zoom: 11
});

// In an SPA, call destroy before removing the page or component.
window.addEventListener("pagehide", () => {
  viewer.destroy();
});

Kaleidr.mount() renvoie une référence de manière synchrone pendant le chargement du paquet produit ; les appels effectués avant que celui-ci soit prêt sont mis en file d’attente. Cette référence fournit toujours destroy() et peut proposer setCamera() ou setTheme() lorsque le produit sélectionné les prend en charge. Les applications monopages doivent relier le démontage au cycle de vie de la route afin d’éviter que des navigations répétées ne créent plusieurs intégrations.

Une carte interactive ne peut pas être le seul moyen d'accéder aux informations essentielles. WCAG 2.2 fournit le cadre pour le contenu Web accessible: donner à la carte un titre significatif et une région étiquetée, publier une liste de localisation équivalente avec les noms, les adresses, les catégories et les actions, confirmer que les utilisateurs de clavier peuvent atteindre et quitter la carte sans pièges, et éviter les marqueurs en couleur seulement.Pour un iframe brut, inclure un attribut title descriptif plutôt qu’une étiquette générique telle que « carte ».

Comment gérer domaines, performances et SEO ?

Un identifiant de partage ne constitue pas un modèle d’autorisation publique sans restriction. Kaleidr Viewer est protégé par le lien de partage et les domaines autorisés par l’éditeur continuent de s’appliquer : une carte limitée à des sites approuvés ne s’affichera pas ailleurs simplement parce qu’une personne connaît son identifiant. Prévoyez les domaines de production, les variantes avec www lorsque les deux sont utilisées, la préproduction et le développement local lorsqu’il est pris en charge. Les tarifs actuels de Kaleidr indiquent la prise en charge des intégrations pour Pro et Enterprise. Viewer ne nécessite pas de clé API, mais les équipes doivent vérifier le forfait, le quota de chargements de carte et les contrôles de publication avant la mise en production (tarifs).

Traiter la carte comme une surface d'application significative.Réserver les dimensions avant le chargement.Paresseux-charge ou report sous les cartes du pli lorsqu'elles ne sont pas essentielles à la vue initiale - native loading="lazy" s'applique aux images brutes, tandis qu'un composant personnalisé peut avoir besoin d'un observateur d'intersection côté hôte ou d'une façade de clic à charge.Ne retardez pas une carte qui est la principale expérience de la page au-dessus du pli.Évitez de charger des piles de carte en double sur une page et de mesurer le temps de chargement, le temps jusqu'à ce que la mémoire interactive, le transfert de tuiles et la mémoire mobile sur les appareils réels.

La page d'hôte a encore besoin d'un texte d'exploration et de description.Indiquez ce que la carte contient près du sommet, publiez des lieux ou des conclusions importants en HTML, utilisez des titres descriptifs et ajoutez des données structurées uniquement lorsqu'elles correspondent au contenu visible.Google documente que le rendu JavaScript introduit des étapes supplémentaires pour les systèmes de recherche (Bases de référencement JavaScript).Placez l'intégration à l'intérieur d'une page canonique stable plutôt que de nombreuses URL quasi-identiques qui ne diffèrent que par le centre de la carte.La création et la publication de cartes avant l'étape d'intégration sont couvertes Constructeur de carte interactif AI.

Verdict final

Utilisez une iframe directe lorsqu’une carte autonome du fournisseur suffit. Choisissez un composant web pour une intégration déclarative propre reposant sur un contrat public maintenu. Employez un SDK JavaScript lorsque l’application hôte doit contrôler la caméra, gérer le cycle de vie, intégrer l’IA, assurer l’authentification ou approfondir l’intégration produit. Kaleidr Viewer est conçu pour des cartes publiées devant s’afficher de manière cohérente sur différents sites sans clé API dans le navigateur : la page hôte charge kaleidr.js, fournit l’identifiant de partage, réserve un conteneur adaptatif et respecte les domaines autorisés. Une intégration réussie charge de façon fiable, explique son objectif, reste utilisable sur mobile et au clavier, expose les informations essentielles hors de la carte et aide le visiteur à accomplir une tâche mesurable.

Intégrer une carte Kaleidr publiée

Publiez une carte dans Kaleidr Studio, copiez son identifiant de partage et ajoutez Viewer au moyen du chargeur JavaScript versionné. La documentation d’intégration de Viewer décrit le contrat du composant et de la messagerie. Consultez Chat, Editor, Tiles, l’authentification et Platform API dans la documentation développeur lorsque la carte doit s’intégrer à un flux produit plus large.

Questions fréquentes

Comment intégrer une carte interactive à un site web ?

Choisissez une carte ou un fournisseur publié, ajoutez son iframe, son composant Web ou son SDK JavaScript à la page, réservez un conteneur réactif, configurez l'accès et fournissez du texte accessible en dehors de la carte.

Une iframe est-elle le moyen le plus simple d’intégrer une carte ?

Habituellement.Un iframe s'adapte lorsque la carte est autonome et que la page a besoin de peu de contrôle.Un composant Web ou un SDK est meilleur lorsque l'hôte a besoin d'un contrat de produit stable, de mises à jour de la caméra, de contrôle du cycle de vie, d'événements ou d'interactions d'IA.

Kaleidr Viewer nécessite-t-il une clé API ?

Non.Le visualiseur actuel est partagé-lien et utilise l’ID de partage de la carte publiée.Les restrictions de domaine autorisé définies par l'éditeur s'appliquent toujours.

Comment rendre une carte intégrée adaptative ?

Donnez à l'emballage et cartographiez les dimensions explicites, utilisez la pleine largeur, réservez une hauteur minimale et ajustez la hauteur ou la disposition pour les écrans étroits.Testez les commandes et les panneaux d'information sur mobile.

Puis-je contrôler une carte Kaleidr intégrée depuis JavaScript ?

Oui.L'intégration impérative de Viewer renvoie une poignée qui peut prendre en charge les mises à jour de la caméra et fournit toujours destroy() pour le déchems.

Références

• Google. Embed a Map. Google Maps Embed API documentation. Accessed 2 August 2026. https://developers.google.com/maps/documentation/embed/embedding-map
• Google. Understand JavaScript SEO Basics. Google Search Central. Accessed 2 August 2026. https://developers.google.com/search/docs/crawling-indexing/javascript/javascript-seo-basics
• Kaleidr. kaleidr.js — the Loader. Kaleidr Developer Docs. Accessed 2 August 2026. https://docs.kaleidr.com/sdk/kaleidr-js
• Kaleidr. kaleidr-map — the Element. Kaleidr Developer Docs. Accessed 2 August 2026. https://docs.kaleidr.com/sdk/kaleidr-map-element
• Kaleidr. Pricing & Plans. kaleidr.com. Accessed 2 August 2026. https://kaleidr.com/pricing
• Kaleidr. Quickstart. Kaleidr Developer Docs. Accessed 2 August 2026. https://docs.kaleidr.com/quickstart
• Kaleidr. Viewer — Embed a Published Map. Kaleidr Developer Docs. Accessed 2 August 2026. https://docs.kaleidr.com/sdk/viewer-embed
• MDN Web Docs. iframe: The Inline Frame Element. Accessed 2 August 2026. https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/iframe
• MDN Web Docs. Using Custom Elements. Accessed 2 August 2026. https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements
• World Wide Web Consortium. Web Content Accessibility Guidelines (WCAG) 2.2. Accessed 2 August 2026. https://www.w3.org/TR/WCAG22/
• web.dev. Optimize Cumulative Layout Shift. Accessed 2 August 2026. https://web.dev/articles/optimize-cls

@misc{kaleidr_viewer_embed,
  title  = {Viewer -- Embed a Published Map},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 2 August 2026},
  url    = {https://docs.kaleidr.com/sdk/viewer-embed}
}

@misc{kaleidr_loader,
  title  = {kaleidr.js -- the Loader},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 2 August 2026},
  url    = {https://docs.kaleidr.com/sdk/kaleidr-js}
}

@misc{mdn_iframe,
  title  = {iframe: The Inline Frame Element},
  author = {{MDN Web Docs}},
  note   = {Accessed 2 August 2026},
  url    = {https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/iframe}
}

@misc{w3c_wcag22,
  title  = {Web Content Accessibility Guidelines 2.2},
  author = {{World Wide Web Consortium}},
  note   = {Accessed 2 August 2026},
  url    = {https://www.w3.org/TR/WCAG22/}
}

@misc{google_javascript_seo,
  title  = {Understand JavaScript SEO Basics},
  author = {{Google}},
  note   = {Google Search Central; accessed 2 August 2026},
  url    = {https://developers.google.com/search/docs/crawling-indexing/javascript/javascript-seo-basics}
}