Aller au contenu principal

Tile

Tile place un fond de carte Kaleidr sur votre page. Choisissez un style, tel que kaleidr-morning ou kaleidr-night, et le SDK l’affiche dans une iframe hébergée par Kaleidr. Votre page ne charge aucune bibliothèque cartographique.

Utilisez Tile si vous souhaitez un fond de carte interactif et esthétique sans avoir à y dessiner vos propres éléments : arrière-plan d’une localisation, panneau « où nous trouver », ou carte sur laquelle le panneau de chat Kaleidr affiche ses résultats.

Si vous utilisez déjà votre propre carte Mapbox, MapLibre, Google Maps ou Leaflet, Tile n’est pas nécessaire. Ajoutez Chat à votre carte.

Vue d’ensemble​

QuestionRéponse
Que faut-il ?Une clé publiable (kld_pk_live_…) ayant la portée maps. Les nouvelles clés l’incluent par défaut.
Quelle offre ?Toutes les offres, y compris Free.
Comment s’affiche-t-il ?Dans une iframe chargée depuis https://map-embed.kaleidr.com.
Comment choisir l’apparence ?Avec style-id. Six styles polyvalents sont listés ci-dessous.
Quel est le coût ?Un chargement de carte par session Tile. Voir Comptabilisation des chargements.
La page peut-elle contrôler la carte ?Elle peut définir et déplacer la caméra, changer le style et écouter les messages de chargement et d’erreur.

Intégration minimale​

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

Trois éléments sont nécessaires :

  1. Une clé. Créez une clé publiable sur kaleidr.com/api-keys. Voir Obtenir une clé API.
  2. Une origine autorisée. Si la clé énumère des origines autorisées, celle de votre page doit y figurer. La page doit être servie en HTTP ou HTTPS et non ouverte depuis un disque.
  3. Une hauteur. L’élément est en display:block par défaut, ce qui permet d’appliquer sa propriété height. L’exemple indique également display:block pour Safari antérieur à 16.4, où l’élément reste en ligne.

Styles​

style-idAspect
kaleidr-morningLumineux : sol blanc, eau cyan, routes blanches.
kaleidr-afternoonSol dans des tons moyens, végétation verte et routes grises.
kaleidr-eveningHeure dorée : sable chaud et tons olive.
kaleidr-nightBleu marine sombre et anthracite, autoroutes ambrées.
kaleidr-plainFond blanc avec frontières et noms de lieux. Les bâtiments 3D apparaissent à partir du zoom 15.
kaleidr-editorialPalette de l’après-midi sans étiquettes, pour les petites cartes ou les cartes décoratives.

Indiquez toujours style-id. Si vous l’omettez, l’intégration utilise le fond de carte par défaut de votre organisation lorsqu’il est défini, et affiche une erreur sinon.

Fonctionnement​

  1. Le SDK envoie votre clé publiable à Kaleidr et reçoit une session Tile de courte durée. Cette étape vérifie la clé, sa portée et l’origine de votre page, et comptabilise un chargement de carte. La réponse contient également le fond de carte par défaut de votre organisation s’il existe. La session ne sert qu’à cela : la carte n’effectue aucun autre appel avec elle.
  2. Le SDK remplace le contenu de l’élément par une iframe affichant le style demandé. L’URL de l’iframe ne porte que l’identifiant de style et la caméra fournie : ni la clé publiable ni le jeton de session n’y figurent.
  3. La carte s’affiche dans l’iframe. La politique de sécurité du contenu de votre page doit seulement autoriser le chargeur, la requête de session et l’iframe.
  4. Une fois la carte dessinée, l’iframe envoie le message kaleidr-embed:ready à votre page.

Actions du visiteur​

Déplacer, faire pivoter et incliner la carte, puis zoomer avec les boutons, un pincement ou la molette. Faire défiler avec le pointeur sur la carte zoome la carte ; avec le pointeur hors de la carte, le défilement déplace la page.

Actions possibles depuis votre page​

  • Définir la caméra initiale avec center, zoom, pitch et bearing.
  • Déplacer la caméra ensuite avec handle.setCamera(...).
  • Changer le style avec handle.setStyle('kaleidr-night'), sans rechargement.
  • Associer un panneau de chat. Une instance Chat peut cibler un élément Tile et y afficher ses résultats.
  • Savoir quand la carte est chargée grâce au message kaleidr-embed:ready.

Comptabilisation des chargements de cartes​

La consommation de Tile est mesurée en chargements de carte, comme les vues de vos cartes publiées. Un chargement est compté chaque fois que le SDK obtient une session Tile :

  • lors du montage de la carte ;
  • à chaque renouvellement de session par le SDK, peu avant son expiration et tant que l’instance est montée. Les sessions durent 15 minutes par défaut ;
  • si vous détruisez puis remontez l’instance, ou retirez l’élément avant de le réinsérer.

Un visiteur qui consulte la page quelques minutes consomme un chargement. Une page laissée ouverte une heure en consomme environ cinq. Il ne s’agit donc pas d’« un chargement par vue de page » : détruisez les instances Tile que vous n’affichez plus.

Lorsque votre organisation a épuisé son quota de chargements sur la période, les nouvelles sessions Tile sont refusées avec HTTP 429. Une nouvelle instance n’affiche rien. Les cartes déjà visibles restent affichées. Voir Quotas et limites de débit.

Limites​

  • Tile est un fond de carte. Votre page ne peut pas y ajouter ses propres marqueurs, couches ou fenêtres contextuelles, et ne reçoit aucun événement de clic ou de caméra. Un panneau de chat associé peut y placer des lieux.
  • Tile est le moyen pris en charge pour afficher un fond de carte Kaleidr.
  • Modifier style-id sur un élément déjà monté n’a aucun effet. Utilisez handle.setStyle ou insérez un nouvel élément.
  • Il n’existe pas de clé Tile distincte. La clé publiable utilisée pour les autres produits Kaleidr fonctionne également pour Tile.

Pour aller plus loin​