Saltar al contenido principal

Viewer

Viewer incorpora a tu página un mapa publicado desde Kaleidr Studio. Se representa en un iframe alojado por Kaleidr, por lo que tu página no necesita cargar una biblioteca de mapas ni utilizar una clave de API. Basta con el identificador del mapa publicado.

Usa Viewer cuando el mapa ya existe en Studio y quieres mostrarlo a los visitantes: un localizador de tiendas, un plano de campus, una ruta de evento o un mapa de datos en un artículo.

De un vistazo​

PreguntaRespuesta
¿Qué necesito?El identificador de un mapa publicado. Sin clave de API ni sesión.
¿Qué plan?Todos los planes, incluido Free. Para publicar necesitas una cuenta de Kaleidr.
¿Cómo se muestra?En un iframe servido desde https://map-embed.kaleidr.com.
¿Qué muestra?El mapa publicado por su autor: marcadores, rutas, capas con estilo, conjuntos de datos y superposiciones de imágenes cargados en el panel Datos de Studio.
¿Cómo lo inserto?Con un <iframe> normal o el elemento <kaleidr-map product="viewer"> del SDK.
¿Cuánto cuesta?Cada visualización cuenta como una carga de mapa para la organización propietaria.
¿Puede la página comunicarse con el mapa?Puede establecer y mover la cámara y escuchar mensajes de carga y error. Nada más.

Integración mínima​

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<kaleidr-map product="viewer"
             share-id="YOUR_MAP_ID"
             style="display:block; height:480px"></kaleidr-map>

Sustituye YOUR_MAP_ID por el identificador que Studio muestra en el código de inserción tras publicar. El elemento tiene display:block por defecto, así que se aplica height. El ejemplo también especifica display:block para Safari anterior a 16.4, donde el elemento sigue siendo inline e ignora height.

Si no puedes añadir scripts a la página (por ejemplo, en un constructor web, un CMS o una herramienta de boletines que admite HTML), utiliza el iframe que genera Studio:

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

Ambos métodos muestran el mismo mapa. Insertar un mapa publicado explica cuándo elegir cada uno.

Cómo funciona​

  1. Publicas un mapa en Studio, que le asigna un identificador y un fragmento de inserción.
  2. Tu página carga el fragmento. El elemento del SDK o el iframe normal apunta a https://map-embed.kaleidr.com/embed/YOUR_MAP_ID.
  3. La página dentro del iframe obtiene y dibuja el mapa publicado junto con los conjuntos de datos y las superposiciones de imágenes que cargó el autor. Si el mapa tiene dominios permitidos, comprueba primero que el dominio de tu página esté en la lista.
  4. Tras dibujar el mapa, el iframe envía a tu página el mensaje kaleidr-embed:ready. Si no puede dibujarlo, envía kaleidr-embed:error y muestra al visitante una breve explicación en lugar del mapa.

Tu página nunca recibe los datos del mapa ni puede acceder al interior del iframe. La biblioteca cartográfica, los estilos y las solicitudes de red permanecen dentro del iframe; por eso tu Política de Seguridad de Contenido solo necesita permitir el frame.

Qué puede hacer el visitante​

  • Desplazar, girar e inclinar el mapa y ampliar con los botones, el gesto de pellizcar o la rueda del ratón. Con el puntero sobre el mapa, la rueda amplía el mapa, como en Studio. Con el puntero fuera del mapa, el desplazamiento mueve la página.
  • Ver dónde están con el botón de ubicación, después de que el navegador les pida permiso.
  • Abrir ventanas emergentes de lugares haciendo clic en el mapa, si el autor las habilitó en Studio.
  • Leer las leyendas y los créditos al pie del mapa.
  • Preguntar a Kaleidr AI sobre el mapa, en el panel Ask Kaleidr cuando el autor activó Control Tower en el mosaico Kaleidr AI de Studio, y en las ventanas emergentes cuando Popup Window está activado. Consulta Kaleidr AI en un mapa publicado.

La inserción es de solo lectura. Los visitantes no pueden editar el mapa y no se guarda ninguna de sus acciones.

Qué puede hacer tu página​

  • Establecer la cámara inicial con center, zoom, pitch y bearing. Por defecto se utiliza la vista guardada por el autor. La cámara indicada por tu página prevalece campo por campo.
  • Mover la cámara más tarde con handle.setCamera(...) o modificando los atributos de cámara del elemento.
  • Saber si el mapa se cargó o falló escuchando los dos mensajes enviados por el iframe.
  • Eliminar el mapa con handle.destroy() o retirando el elemento.

Controles para el propietario del mapa​

Se configuran en Studio, no en el código de inserción:

  • Publicar y retirar la publicación. Un mapa publicado muestra lo que esté guardado en Studio en ese momento; los cambios guardados se hacen públicos cuando se carga de nuevo la inserción, sin volver a publicar. Volver a publicar registra una nueva versión publicada y conserva el mismo enlace. Para modificar el mapa de manera privada, primero retira la publicación y vuelve a publicarlo cuando termines. Retirar la publicación detiene todas las inserciones, y publicarlo de nuevo recupera las mismas URL. Consulta Retirar un mapa publicado.
  • Datos cargados. Los conjuntos de datos y superposiciones de imágenes del mapa publicado se muestran a sus visitantes. Elimina un conjunto de datos en el panel Datos o retira la publicación del mapa para dejar de servirlo. Los enlaces compartidos siguen funcionando tras retirar la publicación; eliminar un conjunto de datos también lo retira de esos enlaces. Un mapa publicado es público: publica únicamente datos que cualquiera pueda leer. Consulta Datos cargados en un mapa publicado.
  • Dominios permitidos. Limita los sitios donde se muestra el mapa. La comprobación usa el referente enviado por la página: si no se envía, no puede mostrarse un mapa restringido por dominio.
  • Kaleidr AI. Activa el panel Ask Kaleidr (Control Tower) y el chat con IA en ventanas emergentes (Popup Window) en el mosaico Kaleidr AI del mapa.

Limitaciones​

  • No se utiliza una clave, por lo que las restricciones de orígenes permitidos de una clave no se aplican. Utiliza los dominios permitidos del mapa.
  • Tu página no puede leer las capas del mapa, añadirle marcadores ni recibir sus eventos de clic.
  • La inserción no ajusta automáticamente su altura: asigna una altura al elemento o iframe.
  • Cuando la organización propietaria agota sus cargas de mapas, la inserción muestra un aviso de límite en lugar del mapa hasta que se reinicia la asignación.
  • Cada visitante descarga íntegramente todos los conjuntos de datos representados, por lo que un mapa con una tabla grande tarda más en aparecer.

Dónde continuar​