Examples

Examples

Load selection state with an iframe

Use an iframe to embed your Waygo map in the Selection State into your website. Set the selection criteria through the iframe's src URL and read the list of currently selected features by listening for selection events.

This page shows:

  • Embed a map in Selection Mode (with criteria)
  • Listen for waygo.selection events from the iframe
  • Extract feature_id + name for selected features (perfect for forms + reservations)

The iframe approach is the simplest embed option: it works in any website and requires no SDKs. If you want deeper integration (custom UI, direct API control, no iframe), use Waygo.js instead.

Alternative: Load selection state with Waygo.js

Example: Selection Mode (criteria: selectable filter is [type=booth], multi-select is true)

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Waygo Map (Selection Mode)</title>
  <style>
    body { margin: 0; padding: 0; }
    #map-container { width: 100%; height: 600px; }
  </style>
</head>
<body>
  <!-- 1) Iframe embed -->
  <div id="map-container">
    <iframe
      id="waygo-map"
      src="https://maps.waygomaps.com/kme-2025/eClHQuAOSue-LI6leXH5Cw/selection/%7B%22type%22%3A%22booth%22%7D/true"
      width="100%"
      height="100%"
      frameborder="0"
      allowfullscreen
    ></iframe>
  </div>

  <!-- Optional: store selected features for forms -->
  <input type="hidden" id="selected-features" name="selectedFeatures" value="[]"
  />

  <script>
    // Only accept messages from the Waygo Maps runtime
    const WAYGO_ORIGIN = "https://maps.waygomaps.com";

    // Source of truth: full feature objects from Waygo
    let selectedFeatures = [];

    window.addEventListener("message", (event) => {
      if (event.origin !== WAYGO_ORIGIN) return;

      const data = event.data;
      if (data?.type !== "waygo.selection") return;

      selectedFeatures = Array.isArray(data.selection) ? data.selection : [];

      // Persist full objects (ID + name stay linked)
      document.getElementById("selected-features").value =
        JSON.stringify(selectedFeatures);

      // Example: extract ID + name when needed
      const selectedFeatureRefs = selectedFeatures.map(f => ({
        feature_id: f.feature_id,
        name: f.name, // e.g. "B203"
      }));

      console.log("Selected features (ID + name):", selectedFeatureRefs);
    });

    // Example: later usage (e.g. on form submit)
    function handleSubmit() {
      const featureIds = selectedFeatures.map(f => f.feature_id);
      const featureNames = selectedFeatures.map(f => f.name);

      console.log("Submitting IDs:", featureIds);
      console.log("Submitting names:", featureNames);
    }
  </script>
</body>
</html>

How to embed a Waygo map in the Selection State

When using an iframe to embed a map with selection state, you append the selection criteria to the iframe URL in the following format:

https://maps.waygomaps.com/{mapId}/{mapViewId}/selection/{encryptedCriteria}/{multiSelect}

Where:

  • {mapId} - Your map identifier
  • {mapViewId} - Your map view identifier
  • {encryptedCriteria} - URL-encoded JSON criteria for selection
  • {multiSelect} - Boolean value (true or false) for multi-select functionality

Selection Criteria Format

The criteria object defines what items should be made selectable in the selections state. Each map feature can be tagged with any data properties in the map editor, and the criteria here can be used to filter exactly the features you want to become selectable on the map.

Only features that fit all the provided criteria will be considered to be selectable. Common criteria include:

Criteria with single-option values

{
    criteria: { type: 'booth', size: '10x10' },
}

Criteria with single and varying-option values

{
    criteria: { type: 'booth', size: ['10x10', '20x20'] },
}

Complex criteria

{
    criteria: { 
        type: 'booth', 
        size: ['10x10', '20x20'],
        amenities: ['power', 'internet'],
        location: 'main-hall'
    },
}

Multi-Select Behavior

The multiSelect parameter (at the end of the iframe URL) controls whether users can select multiple items:

  • true - Users can select multiple items
  • false - Users can only select one item at a time

URL Encoding

When constructing the iframe URL manually, make sure to properly URL-encode the criteria JSON:

const criteria = { type: 'booth', size: '10x10' };
const encodedCriteria = encodeURIComponent(JSON.stringify(criteria));
// Result: %7B%22type%22%3A%22booth%22%2C%22size%22%3A%2210x10%22%7D

Listening to Selection Changes

When the selection state changes, Waygo sends a selection update using window.postMessage that can be listened to securely, through the iframe.

Event name: waygo.selection

Message shape:

{
  "type": "waygo.selection",
  "selection": [
    {
      "feature_id": "59c9cd371fcb4d31a1b7750da943f1e2",
      "name": "620",
      "booking_status": "available",
      "size": "10x10",
      "type": "booth",
      "placement_id": "cbce62814b3b4aec927d54a44ab4e0f7",
      "label_location": "{\"type\":\"Point\",\"coordinates\":[-29.97870291873562,-1.3667641270536344]}"
    },
    {
      "feature_id": "a59c96a15ddd4afcbfafc46769cc9fe7",
      "name": "E08",
      "booking_status": "reserved",
      "size": "20x20",
      "type": "booth",
      "placement_id": "d17d6b2e4fa14b1ab7ecb785f7e432a2",
      "label_location": "{\"type\":\"Point\",\"coordinates\":[-29.97870,-1.36676]}"
    }
  ]
}
  • selection is always an array. It can be empty, or it can contain 1, or many selected features (if multiSelect=true).
  • When multiSelect=true, each waygo.selection event includes all currently selected features in its selection array, not just the last selected feature.

Feature object

Each feature in the selection array will follow a standard structure, with room for customized properties too:

  • feature_id, placement_id and label_location are included in all features.
  • booking_status is added to bookable features by default, and its state is managed by the Reservations API.
  • name is the standard field used for the human-readable name of the feature, if one has been added.
  • All other feature properties can be added and customized directly in the map editor to fit your data needs.

Listen to the waygo.selection event with window.addEventListener

Listen to events coming from only the maps.waygomaps.com origin, for events of the waygo.selection type, then extract each feature.name and feature.feature_id for your internal use, and/or use with the Reservations API.

<script>
    // Only accept messages from the Waygo Maps runtime
    const WAYGO_ORIGIN = "https://maps.waygomaps.com";

    let selectedFeatures = [];

    window.addEventListener("message", (event) => {
        if (event.origin !== WAYGO_ORIGIN) return;

        const data = event.data;
        if (data?.type !== "waygo.selection") return;

        selectedFeatures = Array.isArray(data.selection) ? data.selection : [];

        // ...
    });

    // ...
</script>

Using selection with Reservations API

The selection data extracted from the iframe URL provides all the information needed to facilitate a booking or reservation flow using the Reservations API.

The selection data from iframe URL query parameters gives you the feature_ids needed to create reservations. You can use this data in tandem with the Reservations API to build a complete booking flow.

View Reservations API Documentation

Key Data for Reservations

From the iframe URL query parameters, you can extract:

  • Feature IDs: feature_id from decoded selection data - Required for the reservations API
  • Feature Names: name from decoded selection data - Useful for user confirmation
  • Additional Properties: Can be accessed from the original feature data
// Example: Extract feature IDs for reservation
function handleSelectionChange(selections) {
    const featureIds = selections.map(sel => sel.feature_id);
    console.log('Selected features for reservation:', featureIds);
    
    // Send to your backend to call the Reservations API
    // POST /reservations/v1/{map_id}/{map_view_id}
    // Body: { feature_ids: featureIds, data: {...} }
}

Best Practices

  1. Test your criteria - Make sure your selection criteria matches the available options in your map
  2. Handle errors gracefully - Invalid criteria will result in an empty selection state
  3. Use HTTPS - Always use HTTPS URLs for production deployments
  4. Set appropriate dimensions - Ensure your iframe has adequate width and height for the map content
  5. Consider mobile - Test your iframe on mobile devices to ensure proper responsiveness
  6. Handle CORS restrictions - Be aware that cross-origin iframe access may be limited
  7. Polling frequency - Use reasonable intervals (1-2 seconds) to check for URL changes
  8. Error handling - Always wrap iframe URL access in try-catch blocks
  9. Backend integration - Send selection data to your backend for API calls rather than making them from the frontend