Existing iframe

Use this path when the <iframe> is produced by something you do not control: a server-rendered template, a content management system, or a page that predates the SDK. You set the element's src and attach to it, rather than asking the SDK to create anything.

Examples use a demonstration campus. Every snippet on this site addresses ucba, a publicly available campus with the building muntz-hall and the room 170. Substitute your own campus slug once you have one. Slugs for your campus are listed in your Waylocate console, and the addressing rules are in the reference grammar.

Attaching

<iframe id="map" style="width: 100%; height: 600px; border: 0"></iframe>

import { buildEmbedUrl, connect } from "@waylocate/embed";

const iframe = document.getElementById("map");

iframe.src = buildEmbedUrl({
  campus: "ucba",
  building: "muntz-hall",
  room: "170",
});

const map = await connect({ iframe });

From connect() onward this is the same handle every other integration produces, and the rest of the documentation applies unchanged.

Building the URL

buildEmbedUrl() produces the src. It exists rather than being left to string concatenation because two of the parameters are easy to get wrong in ways that fail silently.

Option	Type	Meaning
campus	string	Campus slug. Required.
building	string	Building to open on load
room	string	Room to select on load. Requires building.
ui	string | string[]	Chrome flags
from	string	Route origin, as a reference
to	string	Route destination, as a reference
nav	"preview" | "live"	Directions mode
hostOrigin	string	The one origin allowed to command this map. Defaults to the current page's origin.
mapOrigin	string	Origin serving the map. Defaults to https://waylocate.com
params	Record<string, string>	Extra query parameters, applied last
reportVersion	boolean	Set false to omit the sdk parameter

hostOrigin

This is the parameter integrations most often get wrong. The map compares the sender of every message against it by exact string equality, and the only thing it can do with a bad value is refuse to listen. The symptom is a map that renders correctly and ignores every command.

buildEmbedUrl() validates the value before it reaches the map and throws INVALID_OPTIONS for anything that is not a bare origin, so the mistake surfaces in your code with a message attached.

The default is window.location.origin, which is correct whenever the SDK runs in the page the map is embedded in. Pass it explicitly when you generate the URL somewhere else, such as during server-side rendering.

buildEmbedUrl({ campus: "ucba", hostOrigin: "https://example.edu" });

Paths, wildcards, and credentials are rejected. http: is accepted only on loopback addresses.

reportVersion

By default the URL carries an sdk parameter naming the package version that produced it. Nothing reads it at runtime. It exists so that map operators can see which SDK builds are deployed from ordinary access logs, including integrations that load the page but never complete a handshake, and it is what makes it possible to keep old versions working rather than guessing at the install base. Set reportVersion: false if you have a policy against version disclosure.

Connect options

Option	Type	Meaning
iframe	HTMLIFrameElement	The element to attach to. Required.
mapOrigin	string	Origin the map is served from. Inferred from the element's src when omitted.
timeoutMs	number	How long to wait for the map to answer
commandTimeoutMs	number	Per-command timeout after connecting
signal	AbortSignal	Cancels the pending connection

connect() does not create or remove the element, so map.destroy() leaves your iframe in the document. Removing it is your responsibility.

Ordering

You can call connect() before, after, or at the same time as setting src. The map announces itself when it loads, and the SDK also asks directly, taking whichever answer arrives first. A listener attached late therefore still connects. This is deliberate: the announcement is a single message with no replay, and requiring hosts to win a race against it would be a poor contract.

Next

• Controlling the map for the command surface.
• URL parameters for the query string buildEmbedUrl() produces, if you need to write it by hand.