Skip to main content

Getting started

This page takes you from an empty project to a map you can command. It should take a few minutes.

Written against @waylocate/embed@0.2.1, which speaks wire protocol waylocate: 1.

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.

1. Install the package​

npm install @waylocate/embed

The package has no runtime dependencies. It contains no map rendering code: the map itself is served by Waylocate, and this package is the interface between it and your page. Installed size is a few kilobytes.

React applications install React alongside it, since the React bindings treat it as a peer dependency:

npm install @waylocate/embed react

If you have no bundler, you can load the same package from a CDN with a <script> tag instead. See JavaScript integration.

2. Give the map a container​

The SDK needs an element to mount into. Size that element yourself; the map fills whatever box it is given.

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

3. Mount the map​

import { mount } from "@waylocate/embed";

const map = await mount({
  container: "#map",
  campus: "ucba",
  building: "muntz-hall",
  room: "170",
});

mount() resolves once the map has loaded and confirmed it is listening. The value it resolves to is a WaylocateMap handle.

4. Send a command​

Every command returns a promise that resolves when the map has acted on it, and rejects with a typed error if it could not.

await map.selection.setRoom("muntz-hall/170");
await map.camera.flyTo({ zoom: 18, bearing: 45, duration: 800 });

5. Listen for what the visitor does​

Events tell you about changes in the map, including changes your own commands caused. The meta.source field says who caused each one, so you can react to visitor actions without reacting to the echo of your own.

const unsubscribe = map.on("selection.changed", (selection, meta) => {
  if (meta.source === "user") {
    openBookingPanel(selection.room);
  }
});

6. Clean up​

Call destroy() when the map's container is going away. This detaches listeners, rejects any command still in flight, and removes the surface the SDK created.

map.destroy();

The result​

Where to go next​

  • How the embed works explains what is running where, and why the handle behaves the way it does. Read this before you build anything substantial.
  • Integration covers the other three ways to embed, including the React component and the no-JavaScript iframe.
  • Controlling the map is the full catalogue of commands, events, and errors.