Référence Viewer
product="viewer" affiche une carte publiée depuis Kaleidr Studio. Le SDK remplace le contenu de la cible de montage par un iframe chargeant https://map-embed.kaleidr.com/embed/<id>. La carte est dessinée dans cet iframe.
| Clé | Aucune. N'en fournissez pas. |
| Offre | Toutes les offres, y compris Free. |
| Affichage | Un iframe depuis https://map-embed.kaleidr.com. |
| Comptabilisation | Un chargement de carte par vue, facturé à l'organisation propriétaire. |
| CSP | script-src https://cdn.kaleidr.com et frame-src https://map-embed.kaleidr.com. |
Pour un tutoriel, consultez Intégrer une carte publiée.
Montage
Avec l'élément :
<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>
Depuis JavaScript :
const handle = Kaleidr.mount('#map', {
product: 'viewer',
shareId: 'YOUR_MAP_ID',
});
Sans utiliser le SDK :
<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>
Barre de chat
layout="bar" transforme Viewer en barre de chat : un seul champ de question sur votre page, sans carte tant qu'aucun visiteur n'a posé de question. Une question ouvre la carte publiée, et la Kaleidr AI de la carte y répond.
<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<kaleidr-map product="viewer" share-id="YOUR_MAP_ID" layout="bar"
chat-title="Ask about the neighborhood"
prompts="Coffee within a short walk|Parks nearby"></kaleidr-map>
Les réponses s'ouvrent à l'un de ces deux endroits :
| Réglage | Effet d'une question |
|---|---|
Sans results-url (par défaut) | La carte s'ouvre par-dessus la page, en occupant toute la fenêtre, et pose la question. Le visiteur la ferme avec son bouton de fermeture. Une question ultérieure s'adresse à la même carte : la conversation continue. |
results-url="/map" | Le navigateur se rend sur cette page avec ?q=<question>. Un Viewer de cette page doté de prompt-param="q" pose la question à l'ouverture de la carte, si le visiteur vient d'une page de même origine. |
Une page de résultats :
<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<kaleidr-map product="viewer" share-id="YOUR_MAP_ID" prompt-param="q"
style="display:block; height:600px"></kaleidr-map>
- La carte répond. La question est transmise au panneau Ask Kaleidr de la carte : celle-ci doit donc avoir Control Tower activé (Studio, Kaleidr AI), et les règles de Kaleidr AI sur une carte publiée s'appliquent : le propriétaire paie, et les domaines autorisés de la carte déterminent où elle répond. Sur une carte sans Control Tower, la carte s'ouvre mais la question n'est pas posée.
- La barre ne charge aucune carte. La carte se charge, et compte comme un chargement de carte, lorsqu'un visiteur pose une question.
- La barre s'affiche dans sa propre shadow root, si bien que le CSS de votre page ne la modifie pas, et ses styles ne nécessitent aucune autorisation
style-src. Elle occupe toute la largeur de l'élément et sa hauteur suit son contenu. - Ses propres libellés suivent
lang, ou la langue du navigateur du visiteur silangn'est pas défini : anglais, espagnol, français, allemand, portugais, japonais, coréen, chinois simplifié et traditionnel, et arabe. Voschat-title,placeholderetpromptss'affichent tels que vous les écrivez. promptpréremplit le champ, ethandle.send()pose la question depuis le code.handle.send('Parks nearby')pose cette question ;handle.send()pose celle qui figure dans le champ.
Le générateur de template.kaleidr.com écrit les deux extraits pour la carte de votre choix.
Mises en page de lieux
layout="locator" et layout="listings" affichent la carte publiée à côté d'une liste d'une collection de la Bibliothèque de lieux que la carte dessine, avec les filtres et les fiches de la collection.
<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<kaleidr-map product="viewer" share-id="YOUR_MAP_ID" layout="locator"
filters="search|category|open_now"
style="display:block; height:600px"></kaleidr-map>
<kaleidr-map product="viewer" share-id="YOUR_MAP_ID" layout="listings"
filters="price|beds|baths"
style="display:block; height:720px"></kaleidr-map>
| Mise en page | La liste | Les repères |
|---|---|---|
locator | Les lieux triés par distance, avec un champ de recherche, un bouton Près de moi, les filtres et un total. Une recherche qui ne correspond à aucun lieu de la liste déplace la carte vers le lieu recherché. | La couche de la collection, telle que stylée dans Studio. |
listings | Des fiches avec photo, sur deux colonnes dans un cadre large, triées par Distance, Prix croissant ou Prix décroissant. | Des étiquettes de prix. |
- La liste est à côté de la carte dans un cadre d'au moins 768 pixels de large, et en dessous, dans un panneau sur la carte que le visiteur fait glisser vers le haut.
- La liste et la carte restent synchronisées. Sélectionner un lieu dans la liste déplace la carte vers lui et ouvre sa fiche ; sélectionner un repère fait défiler la liste jusqu'à lui. La liste, les repères et le total affichent toujours les mêmes lieux.
- La liste affiche 50 lieux à la fois, avec Afficher plus.
- Près de moi demande sa position au visiteur. L'iframe créé par le SDK l'autorise ; un iframe simple a besoin de
allow="geolocation". - Sur une carte qui ne dessine aucune collection, les deux mises en page affichent la carte seule.
filters choisit lesquels des Filtres des visiteurs de la collection afficher, séparés par |. Ils apparaissent dans l'ordre de la collection, quel que soit l'ordre dans lequel vous les écrivez, et un filtre que la collection ne propose pas est ignoré. Sans filters, la mise en page affiche tous les filtres de la collection.
| Filtre | Affiche | Retient |
|---|---|---|
search | Un champ de texte | Les lieux dont le nom, l'adresse ou la catégorie contient le texte. |
category | Des boutons de catégorie, jusqu'aux 30 plus fréquentes | Les lieux de l'une des catégories sélectionnées. |
price | Minimum et maximum | Les lieux dont le prix est dans la fourchette. Un lieu sans prix est masqué dès que la fourchette est resserrée. |
beds, baths | Indifférent, 1+, 2+, 3+, 4+ | Les lieux qui en ont au moins autant. |
open_now | Un interrupteur | Les lieux ouverts en ce moment, dans leur propre fuseau horaire. Les lieux sans horaires sont masqués tant qu'il est activé. |
Tous les filtres définis par un visiteur s'appliquent ensemble.
card définit ce que montre la fiche d'un lieu. auto, la valeur par défaut, est la fiche conçue dans Studio. compact n'affiche que le titre, le sous-titre et les actions, pour un petit cadre.
Les actions de lieu fonctionnent comme la collection les définit. Itinéraire trace l'itinéraire dans la carte et propose Apple Maps et Google Maps ; un Lien s'ouvre dans un nouvel onglet ; Appeler ouvre un lien téléphonique ; une action de demande, comme Schedule a Tour, ouvre le formulaire de demande de l'entreprise par-dessus la carte.
Mise en page guide
layout="guide" ouvre une carte d'établissements avec son panneau Ask Kaleidr à côté : le guide de quartier d'un hôtel, ou la carte des environs d'un lieu. Elle liste une collection Établissements (collection, sinon la première collection Établissements que la carte dessine) et nécessite Control Tower activé. Sur une carte qui ne dessine aucune collection Établissements, la mise en page affiche la carte seule.
<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<kaleidr-map product="viewer" share-id="YOUR_MAP_ID" layout="guide"
style="display:block; height:640px"></kaleidr-map>
- Le chat passe en premier. Dans un cadre de 769 pixels de large ou plus, le panneau fait 400 pixels de large, à gauche de la carte. Plus étroit, c'est une feuille par-dessus la carte à 45 % de sa hauteur, que le visiteur fait glisser jusqu'à 85 %. La mention indiquant que les réponses sont générées par l'IA reste sous le champ.
- Les puces de catégorie au-dessus du champ sont les huit catégories les plus courantes de la collection. Une puce affiche les repères de cette catégorie et demande « Montre-moi catégorie près de point d'ancrage » dans la langue du visiteur. Plan My Day demande « Planifie ma journée autour de point d'ancrage ».
- Le point d'ancrage est l'Repère de la carte, défini dans les paramètres de la carte dans Studio : un lieu d'une collection que la carte dessine, ou un point déposé sur la carte, comme votre hôtel. Il est dessiné comme un repère à part avec son nom, et « près de » dans le guide signifie près de lui. Une carte sans point d'ancrage utilise son centre.
- Le programme de la journée. Lorsqu'on lui demande de planifier une journée, le guide trace un itinéraire qui part du point d'ancrage et visite d'abord des lieux de vos propres collections, puis des données de lieux propres à Kaleidr, et l'affiche sous forme de carte d'étapes nommées avec leurs horaires, dans la langue du visiteur.
- Les fiches des établissements affichent la fiche conçue dans Studio, avec Staff Pick sur les lieux que vous marquez, et en dessous les cartes de vos Connexions. Le contenu connecté n'apparaît que sur les fiches, jamais dans les réponses du guide.
- Demandes. L'action Reserve d'un établissement ouvre le formulaire de demande de l'entreprise.
Le guide dans le flux du chat
Le viewer indique à la Kaleidr AI de la carte quelle mise en page il affiche. Un client de POST /chat/control/stream voit deux champs propres au guide :
| Champ | Où | Forme |
|---|---|---|
layout | Le corps de la requête | "guide" tant qu'une mise en page guide est affichée ; omis sinon, ce qui donne un tour de carte ordinaire. Au plus 16 caractères, sinon la requête est refusée avec 422 invalid_layout. |
itinerary | Un événement du flux, répété sur l'événement end | { title, stops: [{ name, time?, note? }] } : le titre du programme et de 1 à 12 étapes nommées, déjà dans la langue du visiteur. Une note n'apparaît que pour vos propres lieux. |
Un client qui n'affiche pas de programmes peut ignorer l'événement.
Mise en page en direct
layout="live" montre où sont vos véhicules en ce moment et où ils s'arrêtent aujourd'hui : la tournée d'un food truck, une navette, un service mobile. Elle lit deux collections : une collection Véhicules, dont les positions proviennent du suivi en direct, et une collection Arrêts avec les horaires.
<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<kaleidr-map product="viewer" share-id="YOUR_MAP_ID" layout="live"
collection="VEHICLES_COLLECTION_ID" stops="STOPS_COLLECTION_ID"
style="display:block; height:640px"></kaleidr-map>
| Option | Par défaut | Lit |
|---|---|---|
collection | La première collection Véhicules que la carte dessine | Les véhicules affichés en direct. |
stops | La première collection Arrêts que la carte dessine | Les arrêts et leurs plages de service. |
Sur une carte qui ne dessine ni l'une ni l'autre, la mise en page affiche la carte seule. Le panneau est à côté de la carte dans un cadre de 769 pixels de large ou plus, et c'est une feuille par-dessus la carte en dessous.
- Une pastille En direct coiffe le panneau, ou Pas en service quand aucun véhicule n'est en service.
- Une ligne par véhicule affiché : son nom ; En route, À l'arrêt, À suivi de l'arrêt, ou Vu il y a 5 min dès que son dernier signal est plus ancien que le délai Marquer Comme Ancien Après de la flotte ; et Prochain arrêt avec Environ 12 min et une étiquette Estimation.
- Tournée d'aujourd'hui : les arrêts du jour dans l'ordre de leurs plages, chacun avec sa plage, le véhicule qui le dessert et un badge.
- Combien de temps jusqu'à moi ? demande la position du visiteur, ou utilise une position approximative de la ville s'il refuse, et indique le temps que mettraient les véhicules affichés pour le rejoindre. La position sert uniquement à cette estimation et n'est jamais enregistrée.
- Sélectionner un véhicule le suit jusqu'à ce que le visiteur déplace la carte. Sélectionner un arrêt ouvre sa fiche, avec les plages du jour ou la prochaine date de service.
| Badge | Quand |
|---|---|
| Ici maintenant | Le véhicule s'est enregistré à l'arrêt. |
| Fermé aujourd'hui | Le chauffeur a marqué le véhicule fermé pour aujourd'hui. |
| Ouvert maintenant | Une plage de l'arrêt contient ce moment. |
| Ensuite : 11:00–14:00 | L'arrêt a une plage plus tard aujourd'hui. |
| Pas aujourd'hui | L'arrêt n'a aucune plage aujourd'hui. Sa fiche indique la prochaine date de service dans les 14 jours. |
Ce que voit le visiteur se déplace en douceur et ne devine jamais. Un véhicule glisse d'une position signalée à la suivante et ne dépasse jamais son dernier signal. Les positions se rafraîchissent toutes les 10 secondes, sauf si l'auteur de la carte a choisi un autre intervalle (de 5 à 60 secondes), et se mettent en pause quand la page est masquée. Les statuts du jour et les estimations se rafraîchissent chaque minute. Un rafraîchissement qui échoue conserve la dernière image.
Seuls les véhicules en service sont affichés, aussi précisément que le permet la précision publique de la flotte. Un véhicule dont le service se termine disparaît au rafraîchissement suivant.
Chaque durée est une estimation. Elle est calculée à partir de la distance routière et de vitesses habituelles, sans tenir compte du trafic. Elle est arrondie à la minute supérieure et affichée sous la forme Environ 12 min ou Environ 1 h 20 min, jamais comme une heure d'arrivée. Sans itinéraire routier entre les deux, la ligne indique Pas d'estimation. Les itinéraires routiers sont construits à partir des données OpenStreetMap, © contributeurs d'OpenStreetMap, sous ODbL.
Request Pickup est l'action de demande de la collection Arrêts. Lorsque son auteur a activé Laisser les visiteurs choisir la prise en charge et la destination, le visiteur fixe d'abord un lieu de prise en charge, l'arrêt lui-même s'il ne le change pas, et une destination, chacun en cherchant une adresse ou en touchant la carte, puis il remplit le formulaire de demande. Les deux points accompagnent la demande.
Les libellés du panneau suivent la langue du viewer, dans les dix mêmes langues que la barre de chat.
Options
| Option de montage | Attribut | Type | Valeur par défaut | Obligatoire | Description |
|---|---|---|---|---|---|
product | product | 'viewer' | aucune | oui | Sélectionne Viewer. |
shareId | share-id | chaîne | aucune | oui | Identifiant de la carte publiée, tiré du code d'intégration Studio. Doit correspondre à ^[A-Za-z0-9._~-]{1,100}$. |
mapId | map-id | chaîne | aucune | non | Alias de shareId, utilisé seulement si shareId est absent. |
center | center | [longitude, latitude] ; attribut "longitude,latitude" | vue enregistrée | non | Centre initial. |
zoom | zoom | nombre | vue enregistrée | non | Zoom initial ; ignoré au montage en l'absence de center. |
pitch | pitch | nombre, degrés | vue enregistrée | non | Inclinaison initiale. |
bearing | bearing | nombre, degrés | vue enregistrée | non | Rotation initiale. |
viewerBase | viewer-base | URL | https://map-embed.kaleidr.com | non | Origine depuis laquelle se charge l'iframe. Seule l'origine est utilisée. Inutile en production. |
base | base | URL | https://cdn.kaleidr.com | non | Origine depuis laquelle le SDK charge viewer.js. Seule l'origine est utilisée, et uniquement celles autorisées dans Remplacement de la base. |
enabled | flag | booléen | aucune | non | Contrôle par montage du mécanisme d'activation. |
prompt | prompt | chaîne | aucune | non | Question à poser à la Kaleidr AI de la carte à son ouverture. Sur une barre de chat, texte prérempli du champ. 500 caractères au maximum. |
promptParam | prompt-param | chaîne | aucune | non | Lit prompt depuis ce paramètre de requête de l'URL de la page elle-même : q sur la page de résultats d'une barre de chat. Lu uniquement lorsque le visiteur vient d'une page de même origine, afin qu'un lien venu d'ailleurs ne puisse faire poser aucune question à votre carte. |
layout | layout | 'map', 'bar', 'locator', 'listings', 'guide' ou 'live' | 'map' | non | bar monte la barre de chat. locator et listings affichent la carte à côté d'une liste d'une collection : voir Mises en page de lieux. guide ouvre le chat à côté d'une carte d'établissements : voir Mise en page guide. live affiche les véhicules et les arrêts du jour : voir Mise en page en direct. |
collection | collection | string | la première collection du type de la mise en page que la carte dessine | non | Localisateur, annonces et guide : l'identifiant de la collection à lister. En direct : l'identifiant de la collection Véhicules. |
stops | stops | string | la première collection Arrêts que la carte dessine | non | En direct : l'identifiant de la collection Arrêts. |
filters | filters | tableau de chaînes ; l'attribut les sépare par | | tous les filtres de la collection | non | Localisateur et annonces : lesquels de search, category, price, beds, baths et open_now afficher, parmi ceux que la collection propose. |
card | card | 'auto' ou 'compact' | 'auto' | non | Les fiches compact n'affichent que le titre, le sous-titre et les actions. |
prompts | prompts | tableau de chaînes ; l'attribut les sépare par | | aucune | non | Barre de chat : exemples de questions, affichés sous forme de boutons qui les posent. |
title | chat-title | chaîne | aucune | non | Barre de chat : libellé au-dessus du champ. |
placeholder | placeholder | chaîne | « Ask about this map », dans la langue de la barre | non | Barre de chat : texte indicatif du champ. |
accent | accent | couleur CSS | #2da84a | non | Barre de chat : couleur du bouton d'envoi, de l'icône et de l'anneau de focus. |
theme | theme | 'light', 'dark' ou 'auto' | 'light' | non | Barre de chat : ses couleurs. auto suit le réglage système du visiteur. |
lang | lang | étiquette de langue | langue du navigateur du visiteur | non | Barre de chat : langue de ses propres libellés. |
resultsUrl | results-url | URL | aucune | non | Barre de chat : envoie les visiteurs vers cette page avec ?q=<question> au lieu d'ouvrir la carte par-dessus la page. |
publishableKey, styleId, map, mapTarget et contained n'ont aucun effet sur un montage Viewer. Passer une clé est même nuisible : le SDK l'échange contre une session que Viewer n'utilise jamais. Si cet échange est refusé, la carte ne s'affiche pas.
L'identifiant
shareId accepte les deux types d'identifiant créés par Studio pour une carte :
- Identifiant de carte publiée. Il figure dans le code de la page Publier et intégrer et dans l'onglet Intégrer de la fenêtre Partager ; les deux affichent le même identifiant.
- Identifiant de lien de partage. C'est l'identifiant de 16 caractères à la fin de l'URL de l'onglet Partager un lien dans la fenêtre Partager.
L'identifiant de carte publiée affiche la carte telle qu'elle est actuellement enregistrée. Celui d'un lien de partage affiche un instantané créé avec le lien. Kaleidr AI accepte l'un ou l'autre : sur un lien de partage, elle suit les interrupteurs Kaleidr AI de l'instantané, tant que la carte est publiée et sur les domaines autorisés actuels de la carte ; voir Chat sur une carte publiée.
Un identifiant vide ou mal formé ne déclenche pas d'exception. Le SDK écrit
[kaleidr:viewer] Kaleidr map: invalid id "" — must match ^[A-Za-z0-9._~-]{1,100}$.
et rien ne s'affiche. Kaleidr.mount renvoie tout de même un handle dont les méthodes n'ont aucun effet.
URL d'iframe simple
https://map-embed.kaleidr.com/embed/<id>?camera=<lon>,<lat>[,<zoom>]&pitch=<deg>&bearing=<deg>&q=<question>&layout=<layout>&collection=<id>&stops=<id>&filters=<a|b>&card=<card>
| Paramètre de requête | Valeur | Effet |
|---|---|---|
camera | longitude,latitude ou longitude,latitude,zoom | Centre initial et zoom facultatif. |
pitch | nombre, degrés | Inclinaison initiale. |
bearing | nombre, degrés | Rotation initiale. |
q | texte, 500 caractères au maximum | Question à poser à la Kaleidr AI de la carte à son ouverture. Posée uniquement lorsque le Viewer est intégré à une page, et ignorée sur une carte sans Control Tower. |
layout | locator, listings, guide ou live | Une mise en page de lieux, le guide ou la mise en page en direct. Toute autre valeur affiche la carte. |
collection | un identifiant de collection | La collection que la mise en page liste ; sur live, la collection Véhicules. |
stops | un identifiant de collection | Sur live, la collection Arrêts. |
filters | des noms de filtres séparés par | | Les filtres que la mise en page affiche. |
card | auto ou compact | Ce que montre la fiche d'un lieu. |
Le SDK construit la même URL à partir de ses options de caméra, de prompt, layout, collection, stops, filters et card.
Caméra
La caméra initiale combine les sources suivantes. Une source ultérieure remplace uniquement les champs qu'elle fournit.
- La vue par défaut du fond de carte.
- La vue enregistrée par l'auteur dans Studio. Il peut enregistrer des vues distinctes pour les largeurs d'ordinateur, de tablette et de téléphone ; la carte choisit celle correspondant à la largeur de l'iframe. Il peut aussi demander le cadrage automatique du contenu, qui adapte ce contenu au cadre.
- La caméra fournie par la page (
center,zoom,pitch,bearingcomme options ou attributs, oucamera,pitchetbearingdans l'URL d'un iframe simple).
La caméra fournie par votre page prévaut sur la vue de l'auteur, y compris sur une vue adaptée à la largeur d'écran ou au cadrage du contenu. Les champs non fournis conservent les valeurs de l'auteur.
Une carte avec vues adaptées à la largeur ou cadrage du contenu se recadre à chaque redimensionnement de l'iframe jusqu'à ce que le visiteur déplace la carte. Une caméra fournie par votre page désactive ce comportement : après une caméra initiale transmise par la page ou un appel à setCamera, la carte ne se recadre plus automatiquement lors des redimensionnements. setCamera ne modifie que les champs spécifiés et laisse les autres inchangés.
Dans center, la longitude vient en premier : [-0.1276, 51.5072] désigne Londres.
Dimensions
- L'iframe occupe 100 % de la largeur de la cible, n'a pas de bordure et possède des coins arrondis.
- Sa hauteur représente 100 % de la cible si elle a une hauteur au montage ; sinon, elle reste fixée à 500 pixels.
- Le montage remplace les enfants de la cible et applique
position:relative(si aucune position en ligne n'existe) ainsi queoverflow:hidden. <kaleidr-map>utilisedisplay:blockpar défaut, doncheightfonctionne. Attribuez-lui une hauteur. Les exemples conservent aussidisplay:blockpour Safari antérieur à 16.4, où l'élément reste en ligne.
Handle
Kaleidr.mount renvoie immédiatement le handle. Consultez la matrice des handles de tous les produits.
| Membre | Dans Viewer |
|---|---|
handle.product | 'viewer' |
handle.setCamera(camera) | Déplace la carte. |
handle.setTheme(theme) | Non pris en charge ; avertissement sans effet. |
handle.setStyle(style) | Non pris en charge ; avertissement sans effet. |
handle.send(text) | Interroge la Kaleidr AI de la carte comme si le visiteur avait saisi text. Sur une barre de chat, send() sans texte pose la question figurant dans le champ. Une question envoyée pendant qu'une autre reçoit sa réponse attend celle-ci, et une plus récente remplace toute question encore en attente. |
handle.setFilters(filters) | Définit les filtres des visiteurs d'une mise en page de lieux. Sans effet avec la mise en page map. |
handle.showVehiclesLayer(layer) | Dessine ou déplace votre propre couche de véhicules. |
handle.clearVehiclesLayer() | Retire votre couche de véhicules. |
handle.destroy() | Retire l'iframe et cesse d'écouter ses messages. |
setCamera(camera)
handle.setCamera({
center: [2.3522, 48.8566], // [longitude, latitude]
zoom: 12,
pitch: 45,
bearing: -20,
duration: 800, // milliseconds
});
| Champ | Type | Description |
|---|---|---|
center | [number, number] | Longitude, latitude. |
zoom | nombre | Niveau de zoom. Contrairement au montage, zoom fonctionne ici sans center. |
pitch | nombre | Inclinaison en degrés. |
bearing | nombre | Rotation en degrés. |
duration | nombre | Durée de l'animation en millisecondes. Absent ou égal à 0, le déplacement est immédiat. |
Tous les champs sont facultatifs. Ceux que vous omettez conservent leur valeur actuelle.
Vous pouvez appeler setCamera dès le retour de Kaleidr.mount, même à la ligne suivante. Si la carte de l'iframe n'est pas encore prête, l'appel est conservé et appliqué dans l'ordre quand elle se déclare prête. Les 256 derniers appels sont conservés. Si la carte n'a pas signalé sa disponibilité après une attente limitée, normalement 10 secondes après le chargement de l'iframe, les appels sont quand même envoyés et un avertissement apparaît dans la console. Il n'est pas nécessaire d'attendre kaleidr-embed:ready. Pour définir la vue d'ouverture, les options de montage sont plus directes : la carte s'ouvre dans cette vue au lieu de s'y déplacer ensuite.
Il n'existe aucune méthode pour lire la caméra actuelle.
setFilters(filters)
handle.setFilters({
q: 'downtown',
category: ['Outlet', 'Flagship'],
price: [250000, null], // [min, max]; null leaves that end open
beds: 2,
baths: 1,
open_now: true,
});
| Champ | Type | Définit |
|---|---|---|
q | chaîne | Le champ de recherche. |
category | tableau de chaînes | Les catégories sélectionnées. |
price | [number | null, number | null] | Le prix minimum et maximum. |
beds | nombre | Le nombre minimum de chambres. |
baths | nombre | Le nombre minimum de salles de bain. |
open_now | booléen | L'interrupteur Ouvert maintenant. |
Tous les champs sont facultatifs. Le visiteur voit les filtres changer comme s'il les avait définis lui-même, et peut les modifier à nouveau. Un champ pour un filtre que la mise en page n'affiche pas, et tout autre champ, sont ignorés. Comme pour setCamera, un appel fait avant que la carte soit prête est conservé et appliqué dès qu'elle l'est. Un bundle viewer antérieur aux mises en page de lieux n'a pas setFilters ; l'appel ne fait alors rien et affiche un avertissement dans la console indiquant que le montage ne l'expose pas.
showVehiclesLayer(layer)
Dessine sur la carte intégrée des véhicules que votre page suit déjà, comme les positions de votre propre système de répartition. Les données vont de votre page à l'iframe et nulle part ailleurs : rien ne passe par les serveurs de Kaleidr, et le viewer ne télécharge rien pour cette couche.
handle.showVehiclesLayer({
layer_id: 'shuttles',
vehicles: [
{ id: 'bus-1', name: 'Shuttle 1', lat: 40.7411, lng: -73.9897, bearing: 90, color: '#1f6feb' },
{ id: 'bus-2', name: 'Shuttle 2', lat: 40.7527, lng: -73.9772 },
],
});
// Ten seconds later, the same layer_id: each shuttle slides to its new point.
handle.showVehiclesLayer({ layer_id: 'shuttles', vehicles: nextPositions });
handle.clearVehiclesLayer();
| Champ | Type | Description |
|---|---|---|
layer_id | string | Nomme la couche. Le même identifiant la met à jour sur place. |
vehicles | array, 2 000 au plus | Les véhicules à dessiner. |
vehicles[].id | string | Obligatoire. Identifie un véhicule d'un appel à l'autre. |
vehicles[].lat, vehicles[].lng | number | Obligatoire. La position du véhicule. |
vehicles[].name | string | Le libellé dessiné à côté du véhicule. |
vehicles[].color | couleur hexadécimale CSS | La couleur du véhicule. Sans elle, il est dessiné en gris. |
vehicles[].bearing | number, degrés | La direction vers laquelle le véhicule est orienté. |
attribution | string | Un crédit pour vos données, affiché sur la fiche d'un véhicule quand on le touche. |
- Le même
layer_idmet à jour la couche sur place. Chaque véhicule glisse de l'endroit où il est dessiné jusqu'à son nouveau point, sur le temps écoulé depuis votre appel précédent, 30 secondes au plus. Un véhicule absent du nouvel appel disparaît. - Un nouveau
layer_id, ou aucun, remplace la couche. La carte affiche une seule couche de véhicules à la fois. - Un véhicule sans
id, ou sanslatetlngfinis, est ignoré, de même que tout véhicule au-delà du 2 000e. - Pour déplacer les véhicules, rappelez la méthode. Le viewer n'interroge jamais de source pour cette couche.
- Comme pour
setCamera, un appel fait avant que la carte soit prête est conservé et appliqué dès qu'elle l'est.
Les types LiveLayerData et LiveVehicle du SDK déclarent la forme de la couche. showVehiclesLayer et clearVehiclesLayer sont des méthodes du viewer : sur chat, editor et tile, elles affichent un avertissement et ne font rien. Un bundle viewer antérieur à cette couche n'a ni l'une ni l'autre ; l'appel ne fait alors rien et affiche un avertissement dans la console indiquant que le montage ne l'expose pas.
Attributs de l'élément après montage
Sur un <kaleidr-map product="viewer"> monté, modifier center, zoom, pitch ou bearing déplace la carte sans animation. Modifier share-id ou un autre attribut n'a aucun effet. Pour afficher une autre carte, retirez l'élément et insérez-en un nouveau.
Messages de l'iframe
L'iframe envoie des messages à la page qui l'intègre. Deux constituent les signaux publics « chargé » et « échec » :
// The map drew for the first time.
{ type: 'kaleidr-embed:ready', id: string, source: 'publish' | 'share' }
// The map could not load, or part of it failed to draw.
{ type: 'kaleidr-embed:error', id: string | null, code: string, message: string }
window.addEventListener('message', (event) => {
if (event.origin !== 'https://map-embed.kaleidr.com') return;
if (event.source !== iframe.contentWindow) return; // which embed sent it
const msg = event.data;
if (msg?.type === 'kaleidr-embed:ready') onReady(msg);
if (msg?.type === 'kaleidr-embed:error') onError(msg);
});
Avec le SDK, iframe est le premier <iframe> dans la cible : target.querySelector('iframe').
Codes d'erreur
code | Terminal | Signification |
|---|---|---|
no_id | oui | L'URL de l'iframe ne contient aucun identifiant de carte. id vaut null. |
not_found | oui | Aucune carte publiée ni aucun lien de partage n'a cet identifiant : la carte n'a jamais été publiée ou a été dépubliée, la carte du lien de partage a été supprimée ou Kaleidr a retiré le lien, ou l'identifiant est mal saisi. |
domain_not_allowed | oui | La carte est restreinte à certains domaines, et la page n'est pas autorisée ou n'envoie pas de référent. |
map_loads_exhausted | oui | L'organisation propriétaire a épuisé ses chargements de carte pour la période. |
fetch_failed | oui | Impossible de récupérer la carte. |
maplibre_error | non | La carte a démarré, mais un élément n'a pas pu être dessiné. Peut arriver plusieurs fois avant ou après ready. |
Après un code terminal, l'iframe affiche un court message à la place de la carte et n'envoie pas ready.
Règles
readyest envoyé une fois par chargement, après le rendu de la carte et la comptabilisation de la vue.- Le SDK crée l'iframe avec
loading="lazy", donc les messages n'arrivent que lorsqu'il approche de la zone visible. - L'iframe envoie d'autres messages dont le
typecommence parkaleidr-embed:. Le SDK les utilise pour relier Chat à la carte. Ils ne font pas partie du contrat public et peuvent changer ; ne vous appuyez pas dessus. - L'iframe accepte les messages de commande, comme un déplacement de caméra via
setCamera, uniquement de la page qui l'intègre directement. Les autres fenêtres ou frames sont ignorées : appelezsetCameradepuis la page qui contient l'iframe. - Ni le SDK ni l'élément n'émettent d'événements DOM et n'offrent de promesse
ready.
Messages visibles par le visiteur
Ils s'affichent dans l'iframe à la place de la carte :
| Texte | Code |
|---|---|
| "Loading map…" | aucun : la carte se charge |
| "Couldn't find a map id in the URL." | no_id |
| "This map isn't available — it may have been unpublished, paused, or the link is incorrect." | not_found |
| "This map isn't allowed to render on this site. Please contact the map owner." | domain_not_allowed |
| "This map has reached its map load limit. It will be available again when the owner's allowance resets." | map_loads_exhausted |
| "Could not load the map. Please try again in a moment." | fetch_failed |
| "Unexpected error loading the map." | aucun : erreur inattendue au démarrage |
Données importées
Une carte publiée dessine les jeux de données et les superpositions d'images ajoutés par l'auteur dans le panneau Données de Studio. L'iframe les charge directement ; aucune option, aucun attribut ni aucune clé ne sont nécessaires, et les données ne transitent jamais par votre page.
| Comportement | Détails |
|---|---|
| Ce qui apparaît | Tous les jeux de données et superpositions d'images inclus dans la carte publiée, sous forme de couches stylisées par leur auteur. |
| Qui peut les lire | Toute personne pouvant ouvrir la carte. Les domaines autorisés ne rendent pas les données confidentielles. |
| Ce que reçoit le navigateur | Chaque jeu de données complet avec toutes ses colonnes. Un jeu volumineux s'affiche plus lentement. |
| Si un jeu de données ne se charge pas | Le reste de la carte s'affiche sans cette couche. |
| Suppression d'un jeu dans le panneau Données de Studio | Le jeu est supprimé et n'est plus servi sur la carte publiée ni sur les liens de partage qui l'affichaient. Un navigateur qui l'a déjà chargé le conserve ; un lien de téléchargement déjà émis peut rester valide jusqu'à une heure. |
| Dépublication de la carte | La carte et ses données cessent d'être accessibles par son identifiant publié. L'iframe affiche not_found. La republier restaure le même identifiant. |
| Liens de partage | Un lien de partage contient un instantané du design au moment de sa création et continue d'afficher sa carte après la dépublication, sans Kaleidr AI jusqu'à ce que la carte soit republiée. Studio ne permet pas de supprimer ou suspendre un tel lien : il fonctionne jusqu'à la suppression de la carte ou au retrait du lien par Kaleidr à la demande du propriétaire. Voir Liens de partage. |
Données importées sur une carte publiée explique ces cas.
Domaines autorisés
Le propriétaire peut restreindre les sites où la carte s'affiche dans Studio, sous Partager, Intégrer, Domaines spécifiques.
- Un domaine autorisé couvre également ses sous-domaines.
- Le contrôle compare la liste avec le nom d'hôte du référent envoyé par le navigateur pour l'iframe. Sans référent, le contrôle échoue.
- Si le contrôle échoue, l'iframe affiche le message « non autorisé » et envoie
domain_not_allowed. - Une vue refusée par cette vérification n'est pas comptabilisée comme chargement de carte.
Comptabilisation
- Une vue compte pour un chargement de carte dans l'organisation propriétaire.
- Le même visiteur qui revoit la même carte dans les 24 heures n'est pas compté une seconde fois.
- Les vues sur les propres sites de Kaleidr ne sont pas comptées.
- Lorsque le quota est épuisé, l'iframe affiche le message de limite jusqu'à la remise à zéro. Voir Quotas et limites de débit.
Messages de console
| Message | Signification |
|---|---|
[kaleidr] <kaleidr-map> requires product="chat|viewer|editor|tile" | L'élément n'a pas de product valide et n'est pas monté. |
[kaleidr:viewer] Kaleidr map: invalid id "…" — must match ^[A-Za-z0-9._~-]{1,100}$. | L'identifiant est vide ou mal formé. |
[kaleidr:viewer] mount target not found: <selector> | Kaleidr.mount n'a trouvé aucun élément correspondant au sélecteur. |
[kaleidr:viewer] [kaleidr] failed to load https://cdn.kaleidr.com/embed/v1/viewer.js | Le bundle Viewer n'a pas pu charger, en raison du réseau, d'un bloqueur ou de la politique script-src. |
[kaleidr] setStyle() is not supported on product "viewer" — the call is a no-op. … | Une méthode non prise en charge par Viewer a été appelée. |
Non disponible
- Des événements pour les clics, les déplacements de caméra ou les sélections, y compris les fiches et les actions de lieu.
- Lecture de la caméra, des couches ou des données de la carte.
- Ajout de marqueurs ou couches personnalisés à la carte intégrée, en dehors d'une couche de véhicules.
- Modification du fond de carte ou du thème depuis l'intégration.