Inicio rápido

Esta página muestra las tres integraciones funcionales más breves, en el orden habitual de la mayoría de los equipos:

Chat en un mapa que ya utilizas. Un panel que responde preguntas sobre lugares y representa las respuestas en tu mapa mediante marcadores, movimientos de cámara y rutas.
Un mapa publicado. Un mapa diseñado en Kaleidr Studio e insertado en tu página.
Un mapa base. Un mapa base diseñado por Kaleidr, listo para utilizar en tu página.

Cada opción utiliza un único archivo HTML. Las tres funcionan con el plan Free.

Opción	Producto	Clave necesaria	Se muestra
Chat en tu mapa	`chat`	Clave publicable	En tu página, encima de tu mapa
Un mapa publicado	`viewer`	Ninguna	En un iframe de Kaleidr
Un mapa base	`tile`	Clave publicable	En un iframe de Kaleidr

Si prefieres entender primero el modelo, lee Cómo funciona Kaleidr. Si no sabes qué producto necesitas, consulta Elige tu camino.

Antes de empezar

Una cuenta de Kaleidr. Regístrate en kaleidr.com. El plan Free basta para todos los ejemplos de esta página.
Una clave publicable para el chat y el mapa base. Créala en kaleidr.com/api-keys; empieza por kld_pk_live_. Obtener una clave de API explica el formulario. El mapa publicado no necesita clave.
Un servidor web para la página. Sirve el archivo por HTTP, incluso en local. Desde la carpeta que contiene el archivo puedes usar cualquiera de estas opciones:
```
python -m http.server 8000
# or
npx serve -l 8000
```
Después abre http://localhost:8000/your-file.html. No abras el archivo directamente desde el disco: una página file:// no tiene un origen que puedas incluir entre los permitidos para la clave.
El origen de tu página entre los permitidos por la clave, si existe una lista. Una clave sin restricciones de origen funciona desde cualquier sitio. Si contiene una lista, solo funciona desde los orígenes enumerados; añade http://localhost:8000 durante las pruebas.
Una Política de Seguridad de Contenido que permita cargar Kaleidr, si tu sitio la aplica. Si no envías la cabecera Content-Security-Policy, no tienes que configurar nada. En caso contrario, consulta Política de Seguridad de Contenido.

Las tres opciones comienzan con la misma etiqueta script. Es el único archivo que cargas por tu cuenta; cuando montas un producto, la etiqueta obtiene su código.

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>

Chat en tu mapa

Obtendrás un mapa MapLibre GL JS con un panel de chat acoplado dentro. Al preguntar «¿Dónde puedo comer ramen cerca de Bryant Park?», la respuesta llega al panel como flujo de texto, crea un marcador por lugar y mueve la cámara para mostrarlos.

Este ejemplo utiliza MapLibre GL JS. Chat también se conecta a Mapbox GL JS, Google Maps JavaScript API y Leaflet; consulta Mapas compatibles.

1. Crear la página

Guarda el archivo como chat.html y sustituye kld_pk_live_… por tu clave publicable.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Kaleidr Chat on MapLibre</title>
    <link rel="stylesheet" href="https://unpkg.com/maplibre-gl@5.17.0/dist/maplibre-gl.css" />
    <style>
      body { margin: 0; }
      /* The chat panel docks inside this box, so it must be positioned and sized. */
      #stage { position: relative; height: 100vh; }
      #map { position: absolute; inset: 0; }
    </style>
  </head>
  <body>
    <div id="stage">
      <div id="map"></div>
    </div>

    <!-- 1. Your map library, loaded as a page global (window.maplibregl). -->
    <script src="https://unpkg.com/maplibre-gl@5.17.0/dist/maplibre-gl.js"></script>
    <!-- 2. The Kaleidr loader. -->
    <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
    <script>
      const map = new maplibregl.Map({
        container: 'map',
        style: 'https://demotiles.maplibre.org/style.json', // replace with your own style
        center: [-73.9857, 40.7484], // [longitude, latitude]
        zoom: 11,
      });

      const chat = Kaleidr.mount('#stage', {
        product: 'chat',
        publishableKey: 'kld_pk_live_…',
        map,             // the live map instance, not a selector
        contained: true, // dock the panel inside #stage
      });

      // When you remove the map (for example on a route change in a single-page app):
      // chat.destroy();
    </script>
  </body>
</html>

Hay tres detalles importantes en este archivo:

La biblioteca cartográfica es una variable global de la página. El chat encuentra MapLibre en window.maplibregl. Cargar MapLibre mediante una etiqueta script establece esa variable. Si la importas desde npm, asígnala antes de montar: window.maplibregl = maplibregl.
map es el objeto del mapa. Pasa la instancia que creaste, no un selector CSS.
contained: true necesita un contenedor posicionado y con altura. El panel se dibuja dentro del destino de montaje. Sin contained, aparece como una ventana fija en la esquina superior izquierda del navegador.

El estilo de demostración es un mapa mundial de poco detalle. Los marcadores aparecen en las coordenadas correctas, pero usa tu propio estilo para mostrar calles.

2. Servir la página y hacer una pregunta

Inicia un servidor local en la carpeta del archivo y abre http://localhost:8000/chat.html.

Qué deberías ver:

El mapa ocupa la ventana y aparece un panel de chat con un campo de texto en su esquina superior izquierda.
En la pestaña Red del navegador, una petición a https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions devuelve 200. El SDK está intercambiando tu clave por una sesión temporal.
Escribe una pregunta sobre lugares, por ejemplo Where can I get ramen near Bryant Park?. La respuesta llega como texto, aparece un marcador por cada lugar y la cámara se ajusta para mostrarlos. En la pestaña Red verás una petición a …/b2b/v1/chat/control/stream que permanece abierta mientras llega la respuesta.
La consola no muestra líneas que contengan [kaleidr.

3. Si no funciona

Qué ves	Causa	Solución
No aparece el panel y la consola muestra un error CORS para `…/sdk/sessions`, seguido de un error `[kaleidr:chat]`	La clave es incorrecta, está revocada o el origen de la página no está entre los permitidos. La API responde sin cabeceras CORS y el navegador lo presenta como error CORS.	Comprueba la clave. Añade el origen exacto, incluido el puerto, en kaleidr.com/api-keys, o vacía la lista durante las pruebas.
El panel está en la esquina superior izquierda del navegador, fuera del mapa	Falta `contained: true` o no se ha posicionado el destino de montaje	Pasa `contained: true` y asigna al contenedor `position: relative` y una altura.
El panel responde pero no aparecen marcadores	La biblioteca cartográfica no es global en la página, así que el chat no puede crear los marcadores	Carga la biblioteca mediante script o establece `window.maplibregl` antes de `Kaleidr.mount`.

Solución de problemas explica cada síntoma con el texto exacto de la consola.

Siguiente paso: Conectar Chat a MapLibre ofrece la guía completa; Capacidades y límites describe lo que puede y no puede hacer el panel.

Un mapa publicado

Obtendrás en tu propia página un mapa diseñado en Kaleidr Studio. No necesitas clave de API: basta con el identificador público del mapa.

1. Publicar el mapa y copiar su identificador

Abre el mapa en Kaleidr Studio y selecciona Publicar.
En la página Publicar e insertar, elige Activar.
Copia el fragmento bajo Código de inserción. El identificador es la última parte de la dirección: en https://map-embed.kaleidr.com/embed/abc123, es abc123.

Qué deberías ver: el estado del proyecto indica live, y la vista previa bajo el código de inserción muestra el mapa tal como lo verán los visitantes.

2. Crear la página

Guarda el archivo como map.html y sustituye YOUR_SHARE_ID por el identificador copiado.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>A published Kaleidr map</title>
  </head>
  <body>
    <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>

    <kaleidr-map
      product="viewer"
      share-id="YOUR_SHARE_ID"
      style="display:block; height:480px"
    ></kaleidr-map>
  </body>
</html>

El elemento necesita una altura; de lo contrario, el mapa utiliza 500 píxeles. <kaleidr-map> es display:block por defecto y admite una altura. El fragmento también escribe display:block para Safari anterior a 16.4, donde el elemento permanece inline y la altura no surte efecto.

Si no puedes añadir scripts a la página (un constructor web o un campo CMS), usa el iframe normal de la pestaña iFrame de Studio. No necesita cargador:

<iframe
  src="https://map-embed.kaleidr.com/embed/YOUR_SHARE_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>

3. Servir la página

Abre http://localhost:8000/map.html.

Qué deberías ver:

Tu mapa con una altura de 480 píxeles y el ancho de la página, que se abre en la vista guardada en Studio.
Con el puntero sobre el mapa, la rueda lo amplía. Con el puntero junto al mapa, el desplazamiento mueve la página.
En el panel Elementos, un <iframe> dentro del elemento <kaleidr-map> cuya dirección empieza por https://map-embed.kaleidr.com/embed/.

Si el frame muestra "This map isn't available — it may have been unpublished, paused, or the link is incorrect.", el identificador es incorrecto o el mapa no está publicado. Si muestra "This map isn't allowed to render on this site. Please contact the map owner.", el mapa está limitado a otros dominios.

Siguiente paso: Insertar un mapa explica cómo restringir los dominios donde aparece el mapa, y Chat en un mapa publicado permite que los visitantes utilicen el chat sin clave.

Un mapa base

Obtendrás un mapa base diseñado por Kaleidr en tu página: un mapa interactivo listo para usar, sin instalar ninguna biblioteca ni escribir estilos.

1. Crear la página

Guarda el archivo como basemap.html y sustituye kld_pk_live_… por tu clave publicable.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>A Kaleidr basemap</title>
  </head>
  <body>
    <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="-73.9857,40.7484"
      zoom="11"
      style="display:block; height:480px"
    ></kaleidr-map>
  </body>
</html>

style-id identifica el mapa base. Especifica siempre su valor. kaleidr-morning es uno de los estilos generales; Tile enumera los demás.
center utiliza longitude,latitude. Indica center siempre que establezcas zoom: se ignora un zoom sin center.

2. Servir la página

Abre http://localhost:8000/basemap.html.

Qué deberías ver:

El mapa base centrado en Midtown Manhattan, de 480 píxeles de alto.
En la pestaña Red, una petición a https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions devuelve 200, seguida de un iframe que carga desde https://map-embed.kaleidr.com.
Con el puntero sobre el mapa, la rueda lo amplía.

Si no se muestra nada y la consola presenta un error CORS para …/sdk/sessions, la clave es incorrecta o el origen no está entre los permitidos, igual que en el ejemplo de chat.

Cada sesión Tile representa una carga de mapa frente a la asignación mensual de tu organización. Consulta Cuotas y límites de frecuencia.

Siguiente paso: Utilizar Tile explica cómo cambiar los estilos en ejecución y controlar la cámara.

Lo que has cargado

Los tres ejemplos utilizaron los mismos dos componentes:

Kaleidr.mount(target, options) monta un producto desde JavaScript y devuelve inmediatamente un handle. El código del producto se carga en segundo plano y las llamadas hechas al handle antes de que esté listo se guardan y se aplican al completarse la carga.
<kaleidr-map> hace lo mismo desde HTML. Sus atributos corresponden a opciones de montaje escritas con guiones (share-id, style-id, publishable-key), salvo dos excepciones: la opción enabled usa el atributo flag, y la opción title del chat utiliza chat-title.

Usa Kaleidr.mount para añadir chat a tu propio mapa, porque requiere el objeto vivo del mapa. Para los demás productos puedes usar cualquiera de las dos formas.

El handle tiene un método destroy() en todos los productos. Los demás métodos dependen del producto: por ejemplo, setCamera funciona en viewer, tile y editor, pero no en chat. En este último, el asistente mueve el mapa y tú sigues utilizando los métodos de cámara de tu biblioteca. Consulta la matriz completa en El elemento <kaleidr-map>.

Límites que conviene conocer

Chat añade sus propios marcadores, rutas y movimientos de cámara. No modifica tus capas ni marcadores, ni los envía a Kaleidr. Tu página tampoco recibe eventos del panel. Consulta Capacidades y límites.
Viewer y Tile funcionan en un iframe. No puedes añadirles tus propias capas o marcadores. Si los necesitas, conserva tu propio mapa y añádele Chat.
Los mapas base de Kaleidr se muestran mediante Tile. No es compatible cargar estilos o teselas de Kaleidr en tu propia biblioteca cartográfica.
El SDK es para páginas web. No hay paquete npm ni SDK móvil nativo. Los servidores utilizan la API de servidor.
Los montajes con clave consumen tu asignación. Las respuestas de Chat gastan créditos de IA de tu organización y cada sesión Tile consume una carga de mapa. Consulta Cómo funciona Kaleidr.

Qué hacer después

Si quieres	Lee
Conectar Chat a Mapbox GL JS	Conectar Chat a Mapbox
Conectar Chat a MapLibre GL JS	Conectar Chat a MapLibre
Conectar Chat a Google Maps	Conectar Chat a Google Maps
Conectar Chat a Leaflet	Conectar Chat a Leaflet
Situar el panel y adaptar los colores de marca	Temas y diseño
Permitir que los visitantes chateen en un mapa publicado	Chat en un mapa publicado
Insertar un mapa publicado y limitarlo a tus dominios	Insertar un mapa
Mostrar un mapa base y cambiar su estilo	Utilizar Tile
Insertar un editor de mapas en la página	Conectar el editor
Utilizar el SDK desde React, Next.js o Vue	Frameworks
Llamar a Kaleidr desde tu servidor	Inicio rápido del servidor
Basar las respuestas en tus datos empresariales	Tus datos
Publicar en producción	Lista de comprobación de producción

Antes de empezar​

Chat en tu mapa​

1. Crear la página​

2. Servir la página y hacer una pregunta​

3. Si no funciona​

Un mapa publicado​

1. Publicar el mapa y copiar su identificador​

2. Crear la página​

3. Servir la página​

Un mapa base​

1. Crear la página​

2. Servir la página​

Lo que has cargado​

Límites que conviene conocer​

Qué hacer después​

Antes de empezar

Chat en tu mapa

1. Crear la página

2. Servir la página y hacer una pregunta

3. Si no funciona

Un mapa publicado

1. Publicar el mapa y copiar su identificador

2. Crear la página

3. Servir la página

Un mapa base

1. Crear la página

2. Servir la página

Lo que has cargado

Límites que conviene conocer

Qué hacer después