Référence Tile

product="tile" affiche un fond de carte Kaleidr choisi par identifiant de style. Le SDK échange votre clé publiable contre une session Tile, puis remplace le contenu de la cible de montage par un iframe qui charge https://map-embed.kaleidr.com/?style=<style>. La carte est dessinée dans cet iframe.

La session permet à Kaleidr de vérifier la clé, sa portée et l'origine de votre page, de compter le chargement de carte et de fournir le fond de carte par défaut de votre organisation. Elle n'est pas transmise à l'iframe. L'URL de celui-ci contient l'identifiant de style et la caméra fournie (camera, pitch, bearing) : elle ne contient ni clé publiable ni jeton de session, et la carte dans l'iframe ne les utilise pas pour ses requêtes.

Clé	Une clé publiable (kld_pk_live_…). Obligatoire.
Portée	maps. Incluse par défaut dans les nouvelles clés.
Offre	Toutes les offres, y compris Free.
Affichage	Un iframe depuis https://map-embed.kaleidr.com.
Comptabilisation	Un chargement de carte par session Tile.
CSP	script-src https://cdn.kaleidr.com, connect-src https://api.kaleidr.com, frame-src https://map-embed.kaleidr.com.

Pour un tutoriel, consultez Utiliser un fond de carte Kaleidr.

Montage

Avec l'élément :

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<kaleidr-map product="tile"
             publishable-key="kld_pk_live_…"
             style-id="kaleidr-morning"
             center="-0.1276,51.5072" zoom="11"
             style="display:block; height:480px"></kaleidr-map>

Depuis JavaScript :

const handle = Kaleidr.mount('#basemap', {
  product: 'tile',
  publishableKey: 'kld_pk_live_…',
  styleId: 'kaleidr-morning',
  center: [-0.1276, 51.5072],
  zoom: 11,
});

Options

Option de montage	Attribut	Type	Valeur par défaut	Obligatoire	Description
product	product	'tile'	aucune	oui	Sélectionne Tile.
publishableKey	publishable-key	chaîne	aucune	oui	Clé kld_pk_… disposant de la portée maps. Une clé serveur (kld_sk_…) est refusée dans le navigateur avant toute requête.
styleId	style-id	chaîne	fond de carte par défaut de l'organisation, s'il existe	recommandé	Identifiant de la liste ci-dessous ou URL https:// complète d'un document de style. Doit correspondre à ^[A-Za-z0-9._:/~-]{1,200}$.
center	center	[longitude, latitude] ; attribut "longitude,latitude"	vue par défaut du style	non	Centre initial.
zoom	zoom	nombre	vue par défaut du style	non	Zoom initial. Ignoré au montage si center n'est pas fourni.
pitch	pitch	nombre, degrés	vue par défaut du style	non	Inclinaison initiale.
bearing	bearing	nombre, degrés	vue par défaut du style	non	Rotation initiale.
apiBase	api-base	URL	https://api.kaleidr.com/inference-api	non	Destination de l'échange de session. Doit inclure /inference-api. Inutile en production.
viewerBase	viewer-base	URL	https://map-embed.kaleidr.com	non	Origine depuis laquelle se charge l'iframe ; seule l'origine est utilisée. C'est l'hôte de la page de carte, pas des données cartographiques.
base	base	URL	https://cdn.kaleidr.com	non	Origine depuis laquelle le SDK charge tile.js. Seules les origines citées dans Remplacement de la base sont acceptées.
enabled	flag	booléen	aucune	non	Commande par montage du mécanisme d'activation.

shareId, theme, map, mapTarget, contained et tileBase n'ont aucun effet sur un montage Tile.

Identifiants de style

style-id	Apparence
kaleidr-morning	Clair : fond blanc, eau cyan et routes blanches.
kaleidr-afternoon	Fond de teinte intermédiaire, végétation verte et routes grises.
kaleidr-evening	Heure dorée : tons chauds de sable et d'olive.
kaleidr-night	Bleu marine et charbon foncés, autoroutes ambrées.
kaleidr-plain	Fond blanc avec frontières et noms de lieux. Bâtiments 3D à partir du zoom 15.
kaleidr-editorial	Palette de l'après-midi sans étiquettes, pour les petites cartes ou cartes décoratives.

Règles :

• Les identifiants doivent correspondre exactement et sont sensibles à la casse. Il n'existe pas d'alias courts.
• Sans styleId, l'intégration utilise le fond de carte par défaut de l'organisation, transmis avec la session. S'il n'en existe aucun, l'iframe affiche « Couldn't find a map id in the URL. ». Fournissez styleId pour ne pas dépendre de la configuration du compte.
• Un styleId explicite prime toujours sur le style par défaut de l'organisation.
• Un identifiant inexistant entraîne un iframe vide et un message kaleidr-embed:error portant le code maplibre_error.
• Un caractère non autorisé empêche le montage. La console affiche [kaleidr:tile] Kaleidr tile: invalid style "…" — must match ^[A-Za-z0-9._:\/~-]{1,200}$.. Une URL de style ne peut donc pas comporter de chaîne de requête.

Caméra

La caméra initiale correspond à la vue par défaut du style, chaque champ fourni remplaçant sa valeur. Si le style n'a pas de vue par défaut, la carte affiche le monde entier : centre [0, 20], zoom 2, sans inclinaison ni rotation.

• Dans center, la longitude vient en premier : [-0.1276, 51.5072] correspond à Londres.
• Au montage, zoom n'est appliqué que si center est également fourni.
• pitch et bearing sont indépendants de center.

Dimensions

• L'iframe occupe 100 % de la largeur de sa cible, sans bordure et avec des coins arrondis.
• Sa hauteur occupe 100 % de la cible si celle-ci possède déjà une hauteur au montage ; sinon, elle est fixée à 500 pixels.
• Le montage remplace les enfants de la cible et applique position:relative (en l'absence de position en ligne) et overflow:hidden.
• <kaleidr-map> a display:block par défaut, ce qui permet à height de fonctionner. Donnez-lui une hauteur. Les exemples précisent également display:block pour Safari antérieur à 16.4, où l'élément reste en ligne sans cela.

Handle

Kaleidr.mount renvoie le handle de façon synchrone. Consultez la matrice des handles pour les quatre produits.

Membre	Dans Tile
handle.product	'tile'
handle.setCamera(camera)	Déplace la carte.
handle.setStyle(style)	Change le fond de carte sur place.
handle.setTheme(theme)	Non pris en charge ; affiche un avertissement sans effet.
handle.destroy()	Retire l'iframe et arrête le renouvellement des sessions.

setStyle(style)

handle.setStyle('kaleidr-night');

Accepte un identifiant ou une URL complète de style, résolu comme styleId au montage. L'iframe ne se recharge pas, la caméra reste en place et aucun chargement de carte supplémentaire n'est compté. Tile est le seul produit qui prend en charge setStyle.

setCamera(camera)

handle.setCamera({
  center: [2.3522, 48.8566], // [longitude, latitude]
  zoom: 12,
  pitch: 45,
  bearing: -20,
  duration: 1200,            // 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. Si absent ou égal à 0, déplacement immédiat.

Tous les champs sont facultatifs. Les champs omis conservent leur valeur actuelle.

Quand appeler les méthodes

Vous pouvez appeler setCamera et setStyle dès le retour de Kaleidr.mount, même à la ligne suivante. Les appels effectués avant que la carte de l'iframe soit prête sont conservés et appliqués dans l'ordre quand elle se déclare prête. Les 256 derniers sont gardés. Si elle ne se déclare pas prête au terme d'une attente limitée, normalement 10 secondes après le chargement de l'iframe, ces appels sont quand même envoyés, avec un avertissement dans la console. Il n'est pas nécessaire d'attendre kaleidr-embed:ready. Pour la vue et le style initiaux, privilégiez les options de montage afin que la carte s'ouvre directement avec eux.

Attributs de l'élément après montage

Sur un <kaleidr-map product="tile"> déjà monté, modifier center, zoom, pitch ou bearing déplace la carte sans animation. Modifier style-id, publishable-key ou tout autre attribut n'a aucun effet.

Messages de l'iframe

// The basemap drew for the first time.
{ type: 'kaleidr-embed:ready', id: string, source: 'tile' }

// Something failed to draw.
{ type: 'kaleidr-embed:error', id: string, code: 'maplibre_error', message: string }

// No style: none was passed, and the organization has no default basemap.
{ type: 'kaleidr-embed:error', id: null, code: 'no_id', message: string }

id correspond à l'identifiant ou l'URL de style fourni. Avec no_id, il vaut null, l'iframe affiche « Couldn't find a map id in the URL. » et n'envoie pas ready.

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://map-embed.kaleidr.com') return;
  if (event.source !== target.querySelector('iframe')?.contentWindow) return;
  const msg = event.data;
  if (msg?.type === 'kaleidr-embed:ready') onReady(msg);
  if (msg?.type === 'kaleidr-embed:error') onError(msg);
});

• ready est envoyé une seule fois lorsque la carte est dessinée, pas à nouveau après setStyle.
• maplibre_error peut arriver plusieurs fois, avant ou après ready.
• L'iframe utilise loading="lazy", de sorte que les messages n'arrivent que lorsqu'il approche de la zone visible.
• Une session refusée ne produit aucun message, puisqu'aucun iframe n'est créé. Consultez la console.
• L'iframe envoie d'autres messages dont le type commence par kaleidr-embed:. Le SDK les utilise pour relier le Chat à la carte ; ils ne font pas partie du contrat public.

Session et comptabilisation

À chaque montage Tile, le SDK envoie

POST https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions
x-api-key: kld_pk_live_…
content-type: application/json

{"product":"tile"}

et reçoit

{
  "session_token": "kld_sess_live_…",
  "expires_in": 900,
  "product": "tile",
  "basemap_style_id": "kaleidr-morning"
}

basemap_style_id désigne le fond de carte par défaut de l'organisation, ou null si aucun n'est défini.

Chaque échange réussi avec "product":"tile" compte un chargement de carte pour votre organisation. Les échanges se produisent :

Quand	Décompte
Au montage	1
90 secondes avant l'expiration de la session, tant que l'élément reste monté	1 à chaque fois
Quand l'onglet redevient visible et que la session arrive à expiration dans les 90 secondes ou a expiré	1
Lors d'un nouveau montage après destroy(), ou après réinsertion d'un élément retiré	1

Remarques :

• Un renouvellement échoué est retenté toutes les 30 secondes. Il ne retire pas la carte déjà visible.
• Si le premier échange échoue, le montage échoue sans nouvel essai. Remontez l'élément pour réessayer.
• destroy() arrête les renouvellements.
• Les mouvements de caméra, les changements de style et les interactions des visiteurs ne sont jamais comptabilisés.

Un échange Tile est refusé pour la première des raisons applicables :

Statut	detail	Cause
403	publishable_key_required	La clé n'est pas publiable.
403	origin_required	La requête ne comporte aucune origine.
403	origin_not_allowed	L'origine de la page ne figure pas dans les origines autorisées de la clé.
403	product_not_allowed	La clé est limitée à d'autres produits.
403	tier_capability_not_allowed	L'offre n'autorise pas ce produit.
403	insufficient_scope	La clé ne possède pas la portée maps.
429	map_load_quota_exceeded	Le quota de chargements de carte de l'organisation est épuisé.

Avant ces contrôles, l'échange répond 404 sessions_disabled lorsque les sessions sont désactivées sur la plateforme, ou 503 sessions_not_configured en cas de défaillance de la plateforme. Aucun de ces cas n'est lié à votre clé. Consultez tous les codes dans Erreurs.

Associer Tile au Chat

Un montage Chat peut piloter un élément Tile. Attribuez un identifiant à l'élément Tile et pointez vers lui l'attribut map-target de Chat (option mapTarget) :

<div style="position:relative">
  <kaleidr-map id="basemap" product="tile" publishable-key="kld_pk_live_…"
               style-id="kaleidr-morning"
               style="display:block; height:560px"></kaleidr-map>

  <kaleidr-map product="chat" publishable-key="kld_pk_live_…" contained
               map-target="#basemap"
               style="display:block; position:absolute; inset:0; z-index:1; pointer-events:none"></kaleidr-map>
</div>

Sur une carte Tile, l'assistant place des repères avec fenêtres contextuelles, cadre la caméra sur les lieux et dessine des itinéraires, les contours de zones telles qu'une ville et les positions des véhicules en direct. Le tutoriel est dans Utiliser un fond de carte Kaleidr, la disposition dans Thèmes et disposition, et les options dans Référence Chat.

Messages de console

Message	Signification
[kaleidr] <kaleidr-map> requires product="chat|viewer|editor|tile"	L'élément n'a pas de product valide ; rien n'est monté.
[kaleidr:tile] kaleidr session exchange failed (<status>)	Échange refusé. La réponse dans l'onglet Réseau indique la cause : detail pour 403 et map_load_quota_exceeded, error pour 429 rate_limited.
Erreur CORS sur …/sdk/sessions, suivie d'une erreur de récupération [kaleidr:tile]	Clé inconnue ou révoquée, ou origine interdite. Sans en-têtes CORS, le navigateur masque la réponse au SDK.
[kaleidr:tile] Kaleidr: a server key (kld_sk_…) must never be used in the browser — it is a standing secret. Use your publishable key (kld_pk_…) here and keep the server key server-side.	Une clé serveur a été fournie ; aucune requête n'est envoyée.
[kaleidr:tile] Kaleidr tile: invalid style "…" — must match ^[A-Za-z0-9._:\/~-]{1,200}$.	styleId contient un caractère interdit.
[kaleidr:tile] mount target not found: <selector>	Kaleidr.mount n'a trouvé aucun élément correspondant au sélecteur.
[kaleidr:tile] [kaleidr] failed to load https://cdn.kaleidr.com/embed/v1/tile.js	Le bundle Tile n'a pas pu être chargé.
[kaleidr] setTheme() is not supported on product "tile" — the call is a no-op. …	Vous avez appelé une méthode non prise en charge par Tile.
[kaleidr] setStyle() IS supported on product "tile", but this mount did not expose it, so the call did nothing. …	La page utilise une ancienne version de tile.js en cache. Rechargez sans cache.

Non disponible

• Ajouter vos propres repères, calques ou fenêtres contextuelles à la carte.
• Des événements de clic, mouvement de caméra ou sélection.
• Lire la caméra actuelle.
• Utiliser la carte sans iframe.

Voir aussi

• Utiliser un fond de carte Kaleidr
• L'élément <kaleidr-map>
• Le chargeur kaleidr.js
• Quotas et limites de débit