Saltar al contenido principal

Tile

Tile incorpora un mapa base de Kaleidr a tu página. Eliges un estilo, como kaleidr-morning o kaleidr-night, y el SDK lo muestra en un iframe alojado por Kaleidr. Tu página no carga ninguna biblioteca de mapas.

Utiliza Tile si quieres un mapa base atractivo e interactivo sin necesidad de dibujar elementos propios: como fondo para una ubicación, panel de «dónde estamos» o mapa donde un panel de chat de Kaleidr muestre sus respuestas.

Si ya utilizas tu propio mapa Mapbox, MapLibre, Google Maps o Leaflet, no necesitas Tile. Añade Chat a ese mapa.

De un vistazo​

PreguntaRespuesta
¿Qué necesito?Una clave publicable (kld_pk_live_…) con el permiso maps. Las claves nuevas lo incluyen por defecto.
¿Qué plan?Todos los planes, incluido Free.
¿Cómo se muestra?En un iframe servido desde https://map-embed.kaleidr.com.
¿Cómo elijo el aspecto?Con style-id. Abajo se enumeran seis estilos de uso general.
¿Cuánto cuesta?Una carga de mapa por sesión de Tile. Consulta Cómo se contabilizan las cargas de mapas.
¿Puede la página comunicarse con el mapa?Puede establecer y mover la cámara, cambiar el estilo y escuchar mensajes de carga y error.

Integración mínima​

<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>

Tres cosas hacen que funcione:

  1. Una clave. Crea una clave publicable en kaleidr.com/api-keys. Consulta Obtener una clave de API.
  2. Un origen permitido. Si la clave enumera orígenes permitidos, el de tu página debe estar incluido. La página debe servirse mediante HTTP o HTTPS, no abrirse desde el disco.
  3. Una altura. El elemento utiliza display:block por defecto, por lo que se aplica su height. El ejemplo también indica display:block para Safari anterior a 16.4, donde el elemento permanece en línea.

Estilos​

style-idAspecto
kaleidr-morningLuminoso: superficie blanca, agua cian y carreteras blancas.
kaleidr-afternoonTerreno de tono medio con vegetación verde y carreteras grises.
kaleidr-eveningHora dorada: tonos de arena cálida y oliva.
kaleidr-nightAzul marino y carbón oscuros, con autopistas ámbar.
kaleidr-plainLienzo blanco con límites y nombres de lugares. Los edificios 3D aparecen a partir del zoom 15.
kaleidr-editorialLa paleta de tarde sin etiquetas, para mapas pequeños o decorativos.

Indica siempre style-id. Si lo omites, la integración utiliza el mapa base predeterminado de tu organización, si existe, o muestra un error si no se ha configurado ninguno.

Cómo funciona​

  1. El SDK envía tu clave publicable a Kaleidr y recibe una sesión de Tile de corta duración. Este paso comprueba la clave, sus permisos y el origen de tu página, y contabiliza una carga de mapa. La respuesta también incluye el mapa base predeterminado de la organización, si existe. La sesión sirve solo para esto: el mapa no realiza más solicitudes con ella.
  2. El SDK sustituye el contenido del elemento por un iframe que muestra el estilo solicitado. Su URL contiene únicamente el identificador de estilo y la cámara indicada: no incluye ni la clave publicable ni el token de sesión.
  3. El mapa se dibuja dentro del iframe. La Política de Seguridad de Contenido de tu página solo necesita permitir el cargador, la solicitud de sesión y el frame.
  4. Una vez dibujado el mapa, el iframe publica en tu página el mensaje kaleidr-embed:ready.

Qué puede hacer el visitante​

Desplazar, girar e inclinar el mapa, y ampliar mediante los botones, el gesto de pellizcar o la rueda del ratón. Con el puntero sobre el mapa, la rueda amplía el mapa; con el puntero fuera del mapa, el desplazamiento mueve la página.

Qué puede hacer tu página​

  • Establecer la cámara inicial con center, zoom, pitch y bearing.
  • Mover la cámara más tarde con handle.setCamera(...).
  • Cambiar el estilo con handle.setStyle('kaleidr-night'), sin recargar.
  • Añadir un panel de chat. Una instancia de chat puede apuntar a un elemento Tile y representar allí sus respuestas.
  • Saber cuándo se cargó mediante el mensaje kaleidr-embed:ready.

Cómo se cuentan las cargas de mapas​

El uso de Tile se mide en cargas de mapas, la misma unidad que se utiliza para las visitas a tus mapas publicados. Se contabiliza una carga cada vez que el SDK obtiene una sesión de Tile:

  • al montar el mapa;
  • cada vez que el SDK renueva la sesión, poco antes de su vencimiento y mientras la integración siga montada. Las sesiones duran 15 minutos por defecto;
  • cuando destruyes y vuelves a montar la instancia, o eliminas el elemento y lo insertas de nuevo.

Un visitante que mira la página unos minutos consume una carga de mapa. Una página abierta durante una hora consume unas cinco. No equivale a «una por visita de página»: destruye las instancias Tile que ya no muestres.

Cuando tu organización agota sus cargas de mapas del período, las nuevas sesiones de Tile se rechazan con HTTP 429. Una nueva instancia no muestra nada. Un mapa que ya aparece en la página permanece visible. Consulta las asignaciones en Cuotas y límites de frecuencia.

Limitaciones​

  • Tile es un mapa base. Tu página no puede añadirle sus propios marcadores, capas o ventanas emergentes, ni recibe eventos de clic o cámara. Un panel de chat asociado sí puede representar lugares en él.
  • El producto Tile es la forma compatible de mostrar un mapa base de Kaleidr.
  • Cambiar style-id en un elemento ya montado no tiene efecto. Utiliza handle.setStyle o inserta un elemento nuevo.
  • No existe una clave separada para Tile. La clave publicable que utilizas con otros productos Kaleidr sirve también para Tile.

Próximos pasos​