Puedes insertar una experiencia cartográfica interactiva en un sitio web mediante un iframe directo, un componente web reutilizable o un SDK de JavaScript conectado a un mapa en vivo. Usa un iframe para un mapa publicado autónomo, un componente web para HTML sencillo con una capa mantenida y un SDK cuando la página anfitriona deba controlar la cámara, el ciclo de vida o las acciones del producto. Una integración en producción también exige dimensiones definidas, controles de dominio, accesibilidad, texto rastreable y analítica de acciones.
Las secciones siguientes explican cómo elegir el método, configurar Kaleidr Viewer y resolver contenedores adaptables, seguridad, accesibilidad, SEO y errores comunes. Para conectar una conversación a un renderizador en vivo, consulta Cómo añadir un chat con IA a un mapa. Para conocer la categoría SDK, consulta ¿Qué es un SDK de mapas con IA?.
Aspectos esenciales de la inserción
- Primero, el método: Elige iframe, componente web, SDK o biblioteca cartográfica nativa según el control que necesite la página anfitriona, no según la longitud del ejemplo de código.
- Reserva la altura: Define una altura explícita para el contenedor antes de cargar el mapa y evita que se contraiga o desplace el diseño.
- Viewer publicado: Kaleidr Viewer usa
product="viewer"y un ID compartido; el acceso depende del enlace compartido y de los dominios permitidos por el editor.- Texto fuera del lienzo: Los encabezados, resúmenes y listas de lugares mantienen la página útil para usuarios de teclado, tecnologías de asistencia y buscadores.
- Mide tareas: Registra cargas, selecciones, indicaciones y conversiones, no solo impresiones del mapa.
¿Cómo se insertan experiencias cartográficas interactivas?
Esta guía crea una sección de mapa adaptable para un sitio de marketing, una guía de destinos, una página inmobiliaria, un localizador de tiendas, un artículo o un producto de software. La experiencia final incluye un mapa interactivo publicado, un contenedor que funciona en escritorio y móvil, un título claro y un resumen textual fuera del mapa, control opcional de la cámara desde la página anfitriona, restricciones de dominio o credenciales, estados de carga y error, alternativas accesibles a la información exclusiva del mapa y eventos para medir la interacción. Los ejemplos usan Kaleidr Viewer porque permite insertar un mapa publicado mediante un único cargador y un único elemento personalizado; el mismo marco de decisión sirve para elegir entre el iframe de un proveedor, un componente web cartográfico o una implementación propia con Mapbox, Google Maps, MapLibre o Leaflet.
¿Cómo elegir el método de inserción adecuado?
La primera decisión es cuánto control necesita el sitio web del host.Un mapa publicado en una página de contenido generalmente no necesita la misma arquitectura que un mapa dentro de un flujo de trabajo SaaS, así que evite elegir el método más complejo por defecto.
| Método | Mejor ajuste | Control de página de host | Principal compensación |
|---|---|---|---|
| Iframe directo | Mapa autónomo o inserción de proveedor | Bajo | Configuración más rápida, integración limitada |
| Componente web | Mapa publicado reutilizable con HTML simple | Medio | Limpie el marcado; el comportamiento depende del contrato del componente |
| JavaScript SDK | Integración de productos con cámara, ciclo de vida, eventos o IA | Alto | Mayor responsabilidad de la aplicación |
| Biblioteca de mapas nativos | Aplicación de mapa totalmente personalizada | Más Alto | Control máximo, superficie de ingeniería más grande |
Utilice un iframe directo cuando el mapa es autónomo, la página de host solo necesita mostrarlo y el trabajo de ingeniería mínimo es la prioridad.El HTML iframe Element crea un contexto de navegación integrado separado: aislamiento útil, pero otro entorno de documento con sus propios recursos y consideraciones de accesibilidad.Utilice un componente web cuando el equipo desea un elemento HTML declarativo, atributos como el ID de mapa o la cámara son suficientes, y el proveedor mantiene la implementación interna; Elementos personalizados Puede ocultar la carga y la mensajería detrás de un contrato público estable.Utilice un SDK de JavaScript cuando el host debe retener un controlador, actualizar la cámara o el tema, destruir el mapa en los cambios de ruta, adjuntar a un renderista en vivo o coordinar la autenticación del navegador, los eventos o los flujos de trabajo de inteligencia artificial.
¿Cómo funciona la inserción de Kaleidr Viewer?
Kaleidr Viewer inserta un mapa de Kaleidr publicado mediante su ID compartido. Viewer administra su propio mapa y funciona a través de un límite iframe dentro del componente <kaleidr-map>; la página anfitriona puede controlar las funciones compatibles mediante el controlador del SDK y la interfaz de mensajería documentada. El contrato actual tiene cuatro propiedades importantes: product="viewer" selecciona Viewer para mapas publicados; share-id identifica el mapa; el acceso depende del enlace compartido y no exige una clave de API; y siguen aplicándose los dominios permitidos por el editor. Viewer se diferencia de Kaleidr Chat: Viewer administra su mapa, mientras que Chat puede conectarse a una instancia activa de Mapbox, Google Maps, MapLibre o Leaflet que ya se ejecute en la aplicación anfitriona.
Carga una sola vez el cargador versionado desde https://cdn.kaleidr.com/embed/v1/kaleidr.js antes de montar un producto. El cargador define <kaleidr-map>, instala window.Kaleidr y después carga bajo demanda el paquete del producto seleccionado. Una inserción mínima de un mapa publicado coloca el elemento personalizado con una altura explícita:
<kaleidr-map
product="viewer"
share-id="abcd1234"
style="display:block; height:520px;">
</kaleidr-map>
El ejemplo sigue la guía de inicio rápido, la referencia de <kaleidr-map> y la documentación de inserción de Viewer vigentes. Sustituye abcd1234 por el ID compartido del mapa publicado. El mapa debe estar publicado y autorizado para mostrarse en el dominio anfitrión. Usa el componente documentado en lugar de construir una URL interna de Viewer que no forme parte del contrato público.
¿Cómo crear una página de mapa adaptable y accesible?
Un mapa integrado necesita una altura explícita.Sin uno, el contenedor puede colapsar, producir un diseño inestable o volver a un valor predeterminado específico del proveedor.Envuelva el elemento en una carcasa que reserva espacio antes de que se cargue el mapa: ancho completo, una altura mínima y, a menudo, una relación de aspecto de 16:9 en el escritorio con un mínimo fijo más alto en teléfonos estrechos.La reserva de espacio reduce el movimiento inesperado del diseño; las incrustaciones sin dimensiones definidas son una causa común del cambio de diseño acumulativo (Guía web.dev CLS).Prueba el mapa real en lugar de confiar solo en la relación de aspecto: un mapa de pantalla ancha poco profunda a menudo funciona en el escritorio, pero se vuelve difícil de usar en un teléfono.
El elemento Visor observa center, zoom, pitch, bearing, y theme donde se apoye; center Utiliza longitud, orden de latitud.Elija la cámara de apertura para que el propósito del mapa sea claro: distrito destacado, desarrollo y tránsito, o una visión nacional más amplia con una búsqueda o filtro obvio.Cuando la página de host necesite un controlador, monte con la API imperativa después de que el cargador esté presente:
const viewer = Kaleidr.mount("#featured-map", {
product: "viewer",
shareId: "abcd1234",
center: [-0.12, 51.5],
zoom: 11
});
// In an SPA, call destroy before removing the page or component.
window.addEventListener("pagehide", () => {
viewer.destroy();
});
Kaleidr.mount() devuelve un controlador de forma sincrónica mientras se carga el paquete del producto; las llamadas realizadas antes de que esté listo quedan en cola. El controlador siempre ofrece destroy() y puede ofrecer setCamera() o setTheme() cuando el producto seleccionado las admite. Las aplicaciones de página única deben vincular el desmontaje al ciclo de vida de la ruta para que la navegación repetida no cree inserciones duplicadas.
Un mapa interactivo no puede ser la única forma de acceder a información esencial. WCAG 2.2 Proporciona el marco para el contenido web accesible: dar al mapa un encabezado significativo y una región etiquetada, publicar una lista de ubicación equivalente con nombres, direcciones, categorías y acciones, confirmar que los usuarios del teclado pueden llegar y dejar el mapa sin trampas, y evitar marcadores de solo color.Para un iframe en bruto, incluya un atributo title descriptivo en lugar de una etiqueta genérica como “mapa”.
¿Cómo deben abordar los equipos los dominios, el rendimiento y el SEO?
Un ID compartido no constituye un modelo de permiso público sin restricciones. Kaleidr Viewer está protegido por el enlace compartido y siguen aplicándose los dominios permitidos por el editor: un mapa limitado a sitios aprobados no se mostrará en otro lugar solo porque alguien conozca el ID. Planifica la lista de dominios para producción, variantes con www cuando se utilicen ambas, preproducción y desarrollo local cuando sea compatible. Los precios actuales de Kaleidr incluyen la inserción en Pro y Enterprise. Viewer no requiere una clave de API, pero los equipos deben confirmar el plan, la asignación de cargas de mapa y los controles de publicación antes de pasar a producción (precios).
Trate el mapa como una superficie de aplicación significativa.Reserva dimensiones antes de cargar.Carga perezosa o aplaza los mapas por debajo de los pliegues cuando no son esenciales para la vista inicial: nativo loading="lazy" Se aplica a los iframes en bruto, mientras que un componente personalizado puede necesitar un Observedor de Intersección del lado del host o una fachada de clic para cargar.No retare un mapa que sea la experiencia principal de la página por encima del pliegue.Evite cargar pilas de mapas duplicados en una página y mida el tiempo del cargador, el tiempo hasta la transferencia interactiva, la transferencia de mosaicos y la memoria móvil en dispositivos reales.
La página de host todavía necesita texto descriptivo y rastreable.Indique lo que el mapa contiene cerca de la parte superior, publique lugares o conclusiones importantes en HTML, use encabezados descriptivos y agregue datos estructurados solo cuando coincida con el contenido visible.Google documenta que la representación de JavaScript introduce etapas adicionales para los sistemas de búsqueda (Conceptos básicos de JavaScript SEO).Coloque la incrustación dentro de una página canónica estable en lugar de muchas URL casi idénticas que difieren solo por el centro de mapas.La creación y publicación del mapa antes de la inserción paso están cubiertos en Creador de mapas interactivos de AI.
| Error | ¿Qué pasa | Corrección recomendada |
|---|---|---|
| No hay altura de mapa explícito | El mapa colapsa o cambia el diseño | Reserva dimensiones sensibles antes de cargar |
| Uso de una URL de visor interna bruta | El host depende de un detalle indocumentado | Uso <kaleidr-map> o Kaleidr.mount() |
| Dominio no permitido | Trabaja en un solo entorno, falla en la producción | Añadir dominios de implementación aprobados exactos |
| Cargando cada mapa inmediatamente | Innecesario JavaScript, azulejos y datos | Diferir mapas por debajo de los pliegues o utilizar click-to-load |
| Contenido solo para mapas | Los usuarios y los sistemas de búsqueda no cuentan con los hechos esenciales | Añadir un resumen de texto y una lista de ubicación equivalente |
| No hay desmontaje en un SPA | Se acumulan instancias duplicadas y los oyentes | Retenga el controlador y la llamada destroy() |
| Seguimiento solo de vistas de mapa | La exposición se confunden con la finalización de la tarea | Selecciones de seguimiento, direcciones, detalles y conversiones |
| Incorporación de datos operativos privados | Una superficie compartible expone los registros equivocados | Utilizar un flujo de trabajo de aplicación autorizado |
Veredicto final
Usa un iframe directo cuando baste con un mapa autónomo del proveedor. Utiliza un componente web cuando el equipo quiera una inserción declarativa limpia con un contrato público mantenido. Elige un SDK de JavaScript cuando la aplicación anfitriona necesite controlar la cámara, administrar el ciclo de vida, integrar IA, autenticar usuarios o profundizar la integración del producto. Kaleidr Viewer está diseñado para mapas publicados que deben mostrarse de forma coherente en distintos sitios sin una clave de API en el navegador: la página anfitriona carga kaleidr.js, proporciona el ID compartido, reserva un contenedor adaptable y respeta los dominios permitidos. Una buena inserción debe cargar de forma fiable, explicar su propósito, seguir siendo utilizable en móvil y con teclado, exponer la información esencial fuera del mapa y ayudar al visitante a completar una tarea medible.
Insertar un mapa publicado de Kaleidr
Publica un mapa en Kaleidr Studio, copia su ID compartido y añade Viewer mediante el cargador de JavaScript versionado. La documentación de inserción de Viewer explica el contrato del componente y la mensajería. Consulta Chat, Editor, Tiles, autenticación y Platform API en la documentación para desarrolladores cuando el mapa deba formar parte de un flujo de producto más amplio.
Preguntas frecuentes
¿Cómo inserto un mapa interactivo en un sitio web?
Elija un mapa o proveedor publicado, agregue su iframe, componente web o SDK de JavaScript admitido a la página, reserve un contenedor receptivo, configure el acceso y proporcione texto accesible fuera del mapa.
¿Es un iframe la forma más sencilla de insertar un mapa?
Normalmente.Un iframe se ajusta cuando el mapa es autónomo y la página necesita poco control.Un componente web o SDK es mejor cuando el host necesita un contrato de producto estable, actualizaciones de cámara, control del ciclo de vida, eventos o interacción de IA.
¿Kaleidr Viewer requiere una clave de API?
No. No.El Visor actual está cerrado el enlace de compartir y utiliza el ID de compartir del mapa publicado.Las restricciones de dominio permitido definidas por el editor aún se aplican.
¿Cómo hago que un mapa insertado sea adaptable?
Dé la envoltura y el mapa dimensiones explícitas, use el ancho completo, reserve una altura mínima y ajuste la altura o el diseño para pantallas estrechas.Prueba los controles reales y los paneles de información en dispositivos móviles.
¿Puedo controlar un mapa de Kaleidr insertado desde JavaScript?
Sí. Sí.La integración imperativa de Viewer devuelve un controlador que puede admitir actualizaciones de cámara y siempre proporciona destroy() Para derribar.
Referencias
- Google. Embed a Map. Google Maps Embed API documentation. Accessed 2 August 2026. https://developers.google.com/maps/documentation/embed/embedding-map
- Google. Understand JavaScript SEO Basics. Google Search Central. Accessed 2 August 2026. https://developers.google.com/search/docs/crawling-indexing/javascript/javascript-seo-basics
- Kaleidr. kaleidr.js — the Loader. Kaleidr Developer Docs. Accessed 2 August 2026. https://docs.kaleidr.com/sdk/kaleidr-js
- Kaleidr. kaleidr-map — the Element. Kaleidr Developer Docs. Accessed 2 August 2026. https://docs.kaleidr.com/sdk/kaleidr-map-element
- Kaleidr. Pricing & Plans. kaleidr.com. Accessed 2 August 2026. https://kaleidr.com/pricing
- Kaleidr. Quickstart. Kaleidr Developer Docs. Accessed 2 August 2026. https://docs.kaleidr.com/quickstart
- Kaleidr. Viewer — Embed a Published Map. Kaleidr Developer Docs. Accessed 2 August 2026. https://docs.kaleidr.com/sdk/viewer-embed
- MDN Web Docs. iframe: The Inline Frame Element. Accessed 2 August 2026. https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/iframe
- MDN Web Docs. Using Custom Elements. Accessed 2 August 2026. https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements
- World Wide Web Consortium. Web Content Accessibility Guidelines (WCAG) 2.2. Accessed 2 August 2026. https://www.w3.org/TR/WCAG22/
- web.dev. Optimize Cumulative Layout Shift. Accessed 2 August 2026. https://web.dev/articles/optimize-cls
@misc{kaleidr_viewer_embed,
title = {Viewer -- Embed a Published Map},
author = {{Kaleidr}},
note = {Kaleidr Developer Docs; accessed 2 August 2026},
url = {https://docs.kaleidr.com/sdk/viewer-embed}
}
@misc{kaleidr_loader,
title = {kaleidr.js -- the Loader},
author = {{Kaleidr}},
note = {Kaleidr Developer Docs; accessed 2 August 2026},
url = {https://docs.kaleidr.com/sdk/kaleidr-js}
}
@misc{mdn_iframe,
title = {iframe: The Inline Frame Element},
author = {{MDN Web Docs}},
note = {Accessed 2 August 2026},
url = {https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/iframe}
}
@misc{w3c_wcag22,
title = {Web Content Accessibility Guidelines 2.2},
author = {{World Wide Web Consortium}},
note = {Accessed 2 August 2026},
url = {https://www.w3.org/TR/WCAG22/}
}
@misc{google_javascript_seo,
title = {Understand JavaScript SEO Basics},
author = {{Google}},
note = {Google Search Central; accessed 2 August 2026},
url = {https://developers.google.com/search/docs/crawling-indexing/javascript/javascript-seo-basics}
}