Skip to main content

Viewer

Viewer puts a map you published in Kaleidr Studio on your own page. The map renders in an iframe that Kaleidr hosts, so your page loads no map library and needs no API key. The id of the published map is all the embed needs.

Use Viewer when the map already exists in Studio and you want visitors to see it: a store locator, a campus map, a route for an event, a data map in an article.

At a glance​

QuestionAnswer
What do I need?The id of a published map. No API key, no session.
Which plan?Every plan, Free included. Publishing needs a Kaleidr account.
How does it render?In an iframe served from https://map-embed.kaleidr.com.
What does it show?The map as its author published it: markers, routes, styled layers, and the datasets and image overlays uploaded in Studio's Data panel.
How do I embed it?A plain <iframe>, or the <kaleidr-map product="viewer"> element from the SDK.
What does it cost?Each view counts one map load against the map owner's organization.
Can the page talk to the map?It can set and move the camera, and it can listen for a loaded message and an error message. Nothing else.

The smallest embed​

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

Replace YOUR_MAP_ID with the id Studio shows in the embed code after you publish. The element is display:block by default, so the height applies. The snippet also writes display:block, which covers Safari before 16.4, where the element stays inline and ignores height.

If you cannot add a script to the page (a site builder, a CMS, a newsletter tool that accepts HTML), use the iframe that Studio generates instead:

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

Both forms show the same map. Embed a published map explains when to choose each.

How it works​

  1. You publish a map in Studio. Studio gives it an id and an embed snippet.
  2. Your page loads the snippet. The SDK element, or the plain iframe, points an iframe at https://map-embed.kaleidr.com/embed/YOUR_MAP_ID.
  3. The page inside the iframe fetches the published map and draws it, together with the datasets and image overlays its author uploaded. If the map has an allowed-domain list, it first checks that your page's domain is on it.
  4. When the map has drawn, the iframe posts a kaleidr-embed:ready message to your page. If it cannot draw, it posts kaleidr-embed:error and shows the visitor a short explanation in place of the map.

Your page never receives the map's data and cannot reach into the iframe. The map library, its styles and its network requests all stay inside the iframe, which is why your Content Security Policy only needs to allow the frame.

What the visitor can do​

  • Pan, rotate and tilt the map, and zoom with the on-map zoom buttons, a pinch or the scroll wheel. Scrolling with the pointer over the map zooms the map, as in Studio. With the pointer outside the map, scrolling moves your page.
  • Show where they are with the location button, after the browser asks them for permission.
  • Open place popups by clicking the map, when the map's author turned popups on in Studio.
  • Read the map's legends and the credits line at the bottom of the map.
  • Ask Kaleidr AI about the map, in the Ask Kaleidr panel when the author turned on Control Tower in Studio's Kaleidr AI tile, and in the popups when Popup Window is on. See Kaleidr AI on a published map.

The embed is read-only. Visitors cannot edit the map, and nothing a visitor does is saved.

What your page can do​

  • Set the opening camera with center, zoom, pitch and bearing. The default is the view the author saved. A camera your page passes wins over it, field by field.
  • Move the camera later with handle.setCamera(...), or by changing the element's camera attributes.
  • Know when the map loaded or failed by listening for the two messages the iframe posts.
  • Remove the map with handle.destroy(), or by removing the element.

Controls for the map owner​

These live in Studio, not in the embed code:

  • Publish and unpublish. A published map shows the map as it is currently saved in Studio, so a saved edit is public the next time an embed loads, with no re-publish. Re-publish records a new published version and keeps the same link. To change a map privately, unpublish it first and publish it again when you are done. Unpublish stops every embed of the map; publishing again restores the same embed URLs. See Unpublish a map.
  • Uploaded data. The datasets and image overlays a published map draws are shown to its visitors. Delete a dataset in the Data panel, or unpublish the map, to stop serving it. A share link keeps working after an unpublish; deleting a dataset removes it from share links too. A published map is public, so publish only data that anyone may read. See Uploaded data on a published map.
  • Allowed domains. Limit the sites the map renders on. The check uses the referrer your page sends, so a page that sends no referrer cannot show a domain-locked map.
  • Kaleidr AI. Turn on the Ask Kaleidr panel (Control Tower) and AI chat in popups (Popup Window) in the map's Kaleidr AI tile.

Limits​

  • There is no key, so a key-based control such as allowed origins does not apply. Use allowed domains on the map.
  • Your page cannot read the map's layers, add markers to it, or receive click events from it.
  • The embed does not resize its own height. Give the element or iframe a height.
  • When the owner's organization has used its map loads for the period, the embed shows a limit message instead of the map until the allowance resets.
  • Each visitor downloads the whole of every dataset the map draws, so a map built on a large table takes longer to appear.

Where to go next​