Iframe events

Past its initial configuration, the embed speaks a small postMessage API. Your page sends commands in to switch the displayed content, and the embed posts a ready event back once the map settles. Every message is an object with a type field prefixed mountaya:.

Send a command

Post a message to the iframe's contentWindow to change what the embed shows after it has loaded. One command switches the content; the other, mountaya:setSessionToken, renews the session token.

Any override field you include is applied; any you omit leaves the embed's current state unchanged, and so does null on withOverlays or withTerrains. The fields are camelCase: terrain, withOverlays and withTerrains (arrays of slugs), and the boolean toggles withDirectionsControl, withDownloadControl, withNavigationControl, withOverlaysControl, withPreferencesControl, withProfileAnalysis, withProfileCharacteristics, withProfileElevation, withProfilePaceControl, and withStreetviewControl.

Overrides respect your organization's safety rules exactly as the iframe parameters do. A locked-off capability stays off even when a command sets it, and the overlay list is held to your organization's overlay allowlist; no safety rule caps the terrains. Every rule but the elevation chart's is enforced server-side.

Here the same message switches the content and changes the terrain:

{
  "type": "mountaya:setItinerary",
  "itineraryId": "itinerary_456",
  "terrain": "satellite",
  "withOverlays": ["hillshade", "steepness"]
}

Target the embed's origin (https://app.mountaya.com) when you post it.

const iframe = document.querySelector<HTMLIFrameElement>("#mountaya");

iframe?.contentWindow?.postMessage(
  { type: "mountaya:setItinerary", itineraryId: "itinerary_123" },
  "https://app.mountaya.com",
);

The examples page wires the same command into a React component.

Listen for the ready event

The embed posts mountaya:ready each time the map settles: on the initial load, after every mountaya:setItinerary switch, when a load ends in an error, and once more when the embed rebuilds its map with your page's first session token. It rebuilds only where it had already read without that token: with another session_token its src carried, or with none, where your page left its first ask unanswered. Listen with a message handler and key on the message type.

A successful ready event looks like this:

{
  "type": "mountaya:ready",
  "error": null,
  "bounds": [6.82, 45.8, 6.92, 45.95],
  "itineraryId": "itinerary_123",
  "terrain": "topo"
}

The ready event is posted with a wildcard target origin, so check event.origin before trusting the message.

window.addEventListener("message", (event: MessageEvent) => {
  if (event.origin !== "https://app.mountaya.com") {
    return;
  }

  if (event.data?.type !== "mountaya:ready") {
    return;
  }

  if (event.data.error) {
    console.error("Mountaya embed failed:", event.data.error);
    return;
  }

  console.log("Map ready, bounds:", event.data.bounds);
});

Renew the session token

A framed embed asks the page that frames it for a session token when your organization sets require_session_token or its src carries a session_token, because a token lives minutes and only your server can mint one. The embed wizard's preview never asks.

The snippet the embed wizard copies under require_session_token carries a script that answers for you, from your own endpoint, /api/mountaya-embed-session by default. It mints { publishable_key } alone, for the embed's own key, with no surface and no user_id; the script posts nothing for a session that names a user. Paste it once per page; a page with a strict Content Security Policy moves it into its own bundle. Read expiresAt rather than counting five minutes: a token minted moments earlier is answered again while it has more than two minutes left. The quickstart states the endpoint's side.

The full public protocol

mountaya:setItinerary, mountaya:ready, and the session pair mountaya:requestSessionToken and mountaya:setSessionToken are the whole protocol available to an embed on your own domain: two commands in, two events out.

Inspecting the embed's traffic may reveal other mountaya: message types. They are internal to the Mountaya console, and the embed answers them only when the sender shares its own origin, which your page never does. Posting one from your site is ignored rather than refused. Build only on the four above.

Next steps