Saltar al contenido principal

Chat

Kaleidr Chat es un panel de conversación que añades a una página que ya muestra un mapa. El visitante escribe una pregunta ("¿Dónde puedo desayunar cerca de la Tate Modern?"), la respuesta aparece progresivamente en el panel y los lugares mencionados se muestran como marcadores en tu mapa mientras la cámara se mueve para mostrarlos.

El panel se ejecuta en tu página, no en un iframe. Cargas un único script y llamas a Kaleidr.mount con tu clave publicable y el objeto de mapa activo para que el panel se conecte a él. Conservas tu biblioteca cartográfica, estilo, capas y controles.

Qué experimenta el visitante​

  1. Una barra de entrada con el texto Ask Kaleidr aparece en la esquina superior izquierda del mapa.
  2. El visitante envía una pregunta. La barra se expande en una ventana de chat y la respuesta aparece progresivamente como texto.
  3. Cada lugar mencionado en la respuesta se convierte en una tarjeta de resultados del chat y un marcador en el mapa. Con un lugar, la cámara vuela hasta él; con varios, ajusta la vista para incluirlos a todos.
  4. Al pulsar un marcador o resultado se abre una tarjeta del lugar con una breve descripción, fotos, indicaciones y un campo para hacer preguntas adicionales sobre ese lugar.
  5. Pedir indicaciones dibuja una línea de ruta en el mapa y ajusta el encuadre.
  6. Los marcadores de preguntas anteriores permanecen en el mapa durante el resto de la conversación, tanto en los mapas compatibles como en elementos Viewer o Tile de Kaleidr. Cerrar la ventana de chat termina la conversación y elimina sus marcadores y su ruta.

En una ventana gráfica de 768 px de ancho o menos, el panel aparece como una hoja inferior en lugar de una ventana flotante.

Qué hace en tu mapa​

Lo que haceLo que no hace
Añade y elimina sus propios marcadoresLeer, cambiar o eliminar tus capas, fuentes de datos o marcadores
Mueve la cámara hacia un lugar o ajusta la vista para mostrar variosEnviar tus capas, marcadores o área visible a Kaleidr
Dibuja una línea de ruta y luego la eliminaLlamar a tu código cuando ocurre algo
Lee el nivel de zoom actual y lo envía con cada pregunta. En Mapbox GL JS y MapLibre GL JS también lee la cámara y la fuente de las etiquetas de tu estilo, únicamente dentro de la página, para colocar y rotular sus marcadoresTomar el control de los controles o gestos de tu mapa

El comportamiento exacto varía ligeramente según la biblioteca cartográfica, porque cada una ofrece funciones distintas para la cámara y el dibujo. Mapas compatibles contiene la matriz, y Capacidades y límites enumera todas las solicitudes del panel y qué información lleva cada una.

Qué necesita​

RequisitoValor
PlanFree o superior. Las preguntas consumen los créditos de IA de tu organización.
ClaveUna clave publicable, kld_pk_live_…, obtenida en kaleidr.com/api-keys.
Permisoai. Todas las claves nuevas lo incluyen por defecto.
Origen permitidoSi la clave contiene una lista de orígenes permitidos, el origen de la página debe estar en ella.
Biblioteca de mapasMapbox GL JS, MapLibre GL JS, Google Maps JavaScript API o Leaflet, cargada como variable global de la página antes del montaje.
PáginaServida mediante HTTP o HTTPS. Un archivo abierto desde el disco no tiene un origen válido.
Política de seguridad de contenidoSi tu sitio utiliza una, permite los servidores indicados en la página Política de seguridad de contenido.

Obtener una clave de API explica cómo crear la clave y configurar sus orígenes permitidos.

Tres formas de utilizarlo​

Qué tienesQué proporcionasResultado
Tu propio mapa Mapbox, MapLibre, Google o LeafletpublishableKey y mapEl panel controla tu mapa. Es el caso más frecuente.
Un mapa publicado desde Kaleidr StudioNada: inserta el mapa, con Control Tower activado en su mosaico Kaleidr AIEl mapa incluye el panel y el propietario del mapa paga las preguntas. Consulta Kaleidr AI en un mapa publicado.
Ningún mapaSolo publishableKeyUn panel de chat independiente: respuestas y tarjetas de lugares, sin marcadores ni movimientos de cámara.

La página funcional más sencilla​

Esta página muestra un mapa MapLibre con un panel de chat integrado en él. Sustituye la clave, guarda el archivo y sírvelo desde un origen permitido por la clave, por ejemplo http://localhost:8080.

<!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" />
  </head>
  <body>
    <div id="mapHost" style="position:relative; height:520px">
      <div id="map" style="position:absolute; inset:0; z-index:0"></div>
      <div id="chat" style="position:absolute; inset:0; z-index:1; pointer-events:none"></div>
    </div>

    <script src="https://unpkg.com/maplibre-gl@5.17.0/dist/maplibre-gl.js"></script>
    <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',
        center: [-0.12, 51.5],
        zoom: 11,
      });

      Kaleidr.mount('#chat', {
        product: 'chat',
        publishableKey: 'kld_pk_live_…',
        map,
        contained: true,
      });
    </script>
  </body>
</html>

contained: true integra el panel dentro de #chat. Sin esta opción, el panel es una ventana fija en la esquina superior izquierda del área visible del navegador, independientemente de dónde esté el mapa en la página. Temas y diseño explica ambas disposiciones.

Qué no hace​

Explica estas limitaciones a tu equipo antes de desarrollar funciones sobre el panel:

  • Sin callbacks ni eventos. Tu código no recibe avisos cuando un visitante pregunta, llega una respuesta o se pulsa un marcador.
  • Sin posibilidad de proporcionar tu propio contexto. No puedes transmitir al asistente instrucciones de sistema, una personalidad, una lista de tiendas o el contenido de tus capas a través del panel. Las respuestas basadas en los datos subidos por tu organización constituyen una función independiente, sujeta al plan: consulta Tus datos.
  • Sin SDK móvil nativo. El panel está diseñado para páginas web.

Puedes configurar el idioma de las respuestas, el título de la cabecera y el texto de ejemplo del campo de entrada mediante lang, title y placeholder. Si no defines lang, el panel utiliza el atributo <html lang> de tu página. Consulta la Referencia de Chat.

La lista completa está en Capacidades y límites. Si necesitas control total sobre la conversación y la interfaz, llama a la API HTTP desde tu backend: consulta la Guía rápida del servidor.

Próximos pasos​