Viewer

Viewer place sur votre page une carte publiée avec Kaleidr Studio. Elle s'affiche dans une iframe hébergée par Kaleidr : votre page n'a donc besoin ni de bibliothèque cartographique ni de clé API. L'identifiant de la carte publiée suffit.

Utilisez Viewer lorsque votre carte existe déjà dans Studio et que vous souhaitez la montrer aux visiteurs : localisateur de magasins, plan de campus, itinéraire d'événement ou carte de données dans un article.

En bref

Question	Réponse
De quoi ai-je besoin ?	De l'identifiant d'une carte publiée. Aucune clé API ni session.
Quelle offre ?	Toutes, y compris Free. Un compte Kaleidr est nécessaire pour publier.
Comment s'affiche-t-elle ?	Dans une iframe servie depuis https://map-embed.kaleidr.com.
Que montre-t-elle ?	La carte publiée par son auteur : marqueurs, itinéraires, couches stylisées, jeux de données et superpositions d'images chargés dans le panneau Données de Studio.
Comment l'intégrer ?	Avec une simple <iframe> ou l'élément <kaleidr-map product="viewer"> du SDK.
Quel coût ?	Chaque consultation représente un chargement de carte pour l'organisation propriétaire.
Ma page peut-elle commander la carte ?	Elle peut définir et déplacer la caméra et recevoir les messages de chargement et d'erreur. Rien d'autre.

Intégration minimale

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<kaleidr-map product="viewer"
             share-id="YOUR_MAP_ID"
             style="display:block; height:480px"></kaleidr-map>

Remplacez YOUR_MAP_ID par l'identifiant affiché par Studio dans le code d'intégration après publication. L'élément utilise display:block par défaut, ce qui permet d'appliquer height. L'exemple précise également display:block pour Safari antérieur à 16.4, où l'élément reste en ligne et ignore height.

Si vous ne pouvez pas ajouter de script à la page (constructeur de site, CMS ou outil de newsletter acceptant le HTML), utilisez plutôt l'iframe générée par Studio :

<iframe
  src="https://map-embed.kaleidr.com/embed/YOUR_MAP_ID"
  width="100%"
  height="480"
  style="border:0;"
  loading="lazy"
  referrerpolicy="no-referrer-when-downgrade"
  allow="geolocation; microphone; fullscreen; clipboard-write"
  title="Kaleidr map"
></iframe>

Les deux méthodes affichent la même carte. Intégrer une carte publiée explique quand choisir chacune.

Fonctionnement

1. Vous publiez une carte dans Studio, qui lui attribue un identifiant et un extrait de code d'intégration.
2. Votre page charge cet extrait. L'élément SDK ou l'iframe simple charge https://map-embed.kaleidr.com/embed/YOUR_MAP_ID.
3. La page de l'iframe récupère la carte publiée et l'affiche avec les jeux de données et superpositions d'images téléchargés par son auteur. Si la carte possède une liste de domaines autorisés, elle vérifie d'abord que celui de votre page en fait partie.
4. Une fois la carte dessinée, l'iframe envoie kaleidr-embed:ready à votre page. Si l'affichage échoue, elle envoie kaleidr-embed:error et affiche une courte explication à la place de la carte.

Votre page ne reçoit jamais les données de la carte et ne peut pas accéder à l'intérieur de l'iframe. La bibliothèque cartographique, les styles et les requêtes réseau restent dans l'iframe ; votre politique de sécurité du contenu doit donc uniquement autoriser ce cadre.

Ce que peut faire le visiteur

• Déplacer, faire pivoter et incliner la carte, puis zoomer avec les boutons, le geste de pincement ou la molette. Faire défiler avec le pointeur sur la carte zoome la carte, comme dans Studio. Avec le pointeur hors de la carte, le défilement fait défiler la page.
• Afficher leur position grâce au bouton de localisation, après que le navigateur leur a demandé l'autorisation.
• Ouvrir les fenêtres contextuelles des lieux en cliquant, si l'auteur les a activées dans Studio.
• Lire les légendes et la ligne de crédits au bas de la carte.
• Interroger Kaleidr AI sur la carte, dans le panneau Ask Kaleidr lorsque l'auteur a activé Control Tower dans la tuile Kaleidr AI de Studio, et dans les popups lorsque Popup Window est activé. Voir Kaleidr AI sur une carte publiée.

L'intégration est en lecture seule. Les visiteurs ne peuvent pas modifier la carte et aucune de leurs actions n'est enregistrée.

Ce que peut faire votre page

• Définir la caméra initiale avec center, zoom, pitch et bearing. Par défaut, la vue enregistrée par l'auteur est utilisée. Les champs transmis par votre page ont priorité un par un.
• Déplacer la caméra ensuite avec handle.setCamera(...) ou en changeant les attributs de caméra de l'élément.
• Savoir si la carte est chargée ou en erreur en écoutant les deux messages envoyés par l'iframe.
• Retirer la carte avec handle.destroy() ou en supprimant l'élément.

Commandes pour le propriétaire de la carte

Elles se trouvent dans Studio, pas dans le code d'intégration :

• Publier et dépublier. Une carte publiée affiche la version actuellement enregistrée dans Studio. Une modification sauvegardée devient publique au prochain chargement de l'intégration, sans nouvelle publication. Republier enregistre une nouvelle version publiée tout en conservant le même lien. Pour travailler en privé, dépubliez d'abord la carte, puis republiez-la à la fin. Dépublier arrête toutes les intégrations ; republier rétablit les mêmes URL. Voir Dépublier une carte.
• Données téléchargées. Les jeux de données et superpositions d'images de la carte publiée sont visibles par ses visiteurs. Supprimez un jeu de données dans le panneau Données ou dépubliez la carte pour cesser de le diffuser. Les liens de partage fonctionnent encore après dépublication, mais la suppression d'un jeu de données le retire aussi des liens. Une carte publiée est publique : n'y placez que des données accessibles à tous. Voir Données téléchargées sur une carte publiée.
• Domaines autorisés. Limitez les sites pouvant afficher la carte. La vérification utilise le référent envoyé par la page ; sans référent, une carte limitée à certains domaines ne s'affiche pas.
• Kaleidr AI. Activez le panneau Ask Kaleidr (Control Tower) et le chat IA dans les popups (Popup Window) dans la tuile Kaleidr AI de la carte.

Limites

• Il n'y a pas de clé : les restrictions d'origines autorisées associées aux clés ne s'appliquent pas. Utilisez les domaines autorisés de la carte.
• Votre page ne peut pas lire les couches de la carte, y ajouter des marqueurs ni recevoir ses événements de clic.
• L'intégration ne règle pas sa propre hauteur. Fixez une hauteur à l'élément ou à l'iframe.
• Lorsque l'organisation propriétaire a épuisé ses chargements de cartes, l'intégration affiche un message de limite jusqu'à la réinitialisation du quota.
• Chaque visiteur télécharge tous les jeux de données affichés, en entier ; une grande table ralentit donc l'affichage.

Pour aller plus loin

• Intégrer une carte publiée : publier, intégrer, limiter les domaines et vérifier le résultat.
• Référence Viewer : options, handle, messages et codes d'erreur.
• Chat sur une carte publiée : permettre aux visiteurs d'interroger la carte.
• Politique de sécurité du contenu : les deux directives nécessaires à Viewer.