1. Meridian Platform Documentation
  2. Developers
  3. Web SDK

Menu

Articles in this section

The Meridian Web SDK Follow

Avatar
Shawn Kilburn
  • Updated

The Meridian Web SDK officially supports evergreen versions of Firefox, Google Chrome, Microsoft Edge, and Safari browsers.

Overview

The Meridian Web SDK is a JavaScript library you can use to add dynamically updating and interactive Meridian maps to your site.

Get Started

Before you can use the Meridian Web SDK, you’ll need to obtain a read-only API token from the Meridian Editor.

MeridianSDK.init({
  api: MeridianSDK.createAPI({
    // Use `environment: "eu"` to use the SDK from the EU  
    environment: "production",
    token: "Insert your read-only token here"
  })
});

var element = document.getElementById("meridian-map");
var map = MeridianSDK.createMap(element, {
  locationID: "Insert your location ID here",
  floorID: "Insert your floor ID here"
});

// Later on...
map.update({
  placemarks: {
    filter: function() {
      return false;
    }
  },
  tags: {
    filter: function() {
      return false;
    }
  }
});

You can find the location and floor IDs for a specific map by opening that map in the Meridian Editor. The URL for the map page contains the IDs you’ll need:

https:// edit.meridianapps.com /apps/ location ID /versions/1/maps/ floor ID /placemarks

MeridianSDK.init(options) 

MeridianSDK.init({
  api: MeridianSDK.createAPI({
    environment: "production",
    token: "Insert your read-only token here"
  })
});
  • options: an object with any of the following keys:

Calling init is optional. You can pass the API instance directly to [createMap].

var apiOrg1 = MeridianSDK.createAPI({
  token: "Insert Org 1 token here"
});
var apiOrg2 = MeridianSDK.createAPI({
  token: "Insert Org 2 token here"
});
MeridianSDK.createMap(elementOrg1, {
  api: apiCustomer1,
  locationID: "Insert Org 1 location ID here",
  floorID: "Insert Org 1 floor ID here"
});
MeridianSDK.createMap(elementOrg2, {
  api: apiCustomer2,
  locationID: "Insert Org 2 location ID here",
  floorID: "Insert Org 2 floor ID here"
});

To find your organization ID, in the Meridian Editor sidebar menu, click Organization, and then in the Organization Details section find ORGANIZATION ID. You can also get the organization ID from the Editor URL:

https:// edit.meridianapps.com /w/organization/ organization ID

MeridianSDK.createMap(element, options)

var element = document.getElementById("meridian-map");
var map = MeridianSDK.createMap(element, {
  locationID: "Insert your location ID here",
  floorID: "Insert your floor ID here"
});
// Toggle tags/placemarks after 10 seconds
setTimeout(function() {
  map.update({
    placemarks: {
      filter: function() {
        return false;
      }
    },
    tags: {
      filter: function() {
        return false;
      }
    }
  });
}, 10000);
  • element: the DOM element where the map should be rendered.
  • options: an object with any of the following keys:

    • locationID: (required) the location ID.

    • mapID: (required) the floor ID.

    • width: (default = "100%") map width as a CSS length string.

    • height: (default = "400px") map height as a CSS length string.

    • showFloorsControl: (default = true) show the UI control to allow switching floors.

    • showTagsControl: (default = true) show the UI control to allow browsing Tags.

    • api: (default = the api object passed to init) the API object returned by createAPI.

    • tags: (default = {}) an object with any of the following keys:

      • filter: (default = function() { return true; }) boolean predicate function passed to array .filter to filter the array of Tags. 
          var element = document.getElementById("meridian-map");
  var map = MeridianSDK.createMap(element, {
locationID: "INSERT YOUR LOCATION ID HERE",
floorID: "INSERT YOUR FLOOR ID HERE",
tags: {
  filter: function(tag) {
return tag.mac === "CC78ABC6CB63";
  }
}
  });
      • showControlTags: (default = false) Control Tags are shown when true.
      • disabled: (default = false) disable clicking on Tags when true.

    • placemarks: (default = {}) an object with any of the following keys:

      • filter: (default = function() { return true; }) boolean predicate function passed to array .filter to filter the array of placemarks. 
          var element = document.getElementById("meridian-map");
  var map = MeridianSDK.createMap(element, {
locationID: "INSERT YOUR LOCATION ID HERE",
floorID: "INSERT YOUR FLOOR ID HERE",
placemarks: {
  filter: function(placemark) {
return placemark.type === "water_fountain";
  }
}
  });
      • showHiddenPlacemarks: (default = false) hidden placemarks are shown when true.
      • disabled: (default = false) disable clicking placemarks when true.

    • onTagsUpdate(tags): (optional) callback function called whenever any Tags are updated, receiving an object with the following keys:

      • tag.allTags: an array of all Tags heard on the current floor. Ignores the Tags filter function but still respects the showControlTags setting.
      • tag.filteredTags: an array of all Tags currently shown on the current floor and filtered by any specified filters.

    • onTagClick(data, options): (optional) callback function called whenever a Tag is clicked, receiving the Tag data and an options object. The options object contains a preventDefault function. Call options.preventDefault() to prevent the overlay from appearing.

    • onPlacemarkClick(data, options): - (optional) callback function called whenever a placemark is clicked, receiving the placemark data and an options object. The options object contains a preventDefault function. Call options.preventDefault() to prevent the overlay from appearing.

    • onFloorsUpdate(floors): (optional) callback function called when the Floors are loaded, receiving all Floors data in the format provided by the Meridian API.

    • shouldMapPanZoom(event): (optional) callback function called when the user attempts to pan or zoom the map.

      Return true to allow the pan or zoom action, false to prevent it. This should be used to require holding down a modifier key like alt or require at least two fingers to pan the map, which is useful for areas where the map could easily interrupt scrolling behavior. Use the function MeridianSDK.restrictedPanZoom if you want this behavior, which is implemented as follows: 

        function restrictedPanZoom(event) {
if (event.type === "wheel" && !event.altKey) {
  return false;
} else if (event.type === "touchstart") {
  return event.touches.length >= 2;
}
return true;
  }

      You should handle all three of these event types to manage pan and zoom across various devices: mousedown, wheel, touchstart.

Returns an API object with the following properties:

  • update(options): a method that merged the initial options and the options passed here and updates the map.

  • zoomToDefault(): a method to zoom the map to the initial zoom level and position.

  • zoomToPoint(options): a method to pan and zoom to a specific point on the map, takes an object with x, y, and scale, which are all numbers.

    map.zoomToPoint({
  x: tag.x,
  y: tag.y,
  scale: 2
});

MeridianSDK.createAPI(options) 

var api = MeridianSDK.createAPI({
  environment: "production",
  token: "Insert your read-only token here"
});
  • options: an object with any of the following keys:
    • environment: defaults to "production"; valid values are: "production" or "eu".
    • token: a read-only API token obtained from the Meridian Editor.

Returns an API object with the following properties:

  • token: the API token.
  • environment: the API environment.
  • axios: an instance of axios configured with a base URL for the current environment and including an HTTP header with the token.
  • openStream(options): a function to open a streaming connection for near real-time Tag updates.

api.openStream(options) 

var api = MeridianSDK.createAPI({
  environment: "production",
  token: "Insert your read-only token here"
});

var connection = api.openStream({
  locationID: "Insert your location ID here",
  floorID: "Insert your floor ID here",
  onInitialTags: function(tagArray) {
    console.log(tagArray);
  },
  onTagLeave: function(tag) {
    console.log(tag);
  },
  onTagUpdate: function(tag) {
    console.log(tag);
  },
  onClose: function() {
    console.log("Closing!");
  },
  onException: function(err) {
    console.log("An error occurred:", err);
  }
});

// Close connection after 10 seconds
setTimeout(function() {
  connection.close();
}, 10000);
  • options: an object with any of the following keys:
    • locationID: the location ID.
    • floorID: the floor ID.
    • onInitialTags(tags): an optional callback function called with an array of Tag data after the stream connection is successful.
    • onTagUpdate(tag): an optional callback function called with a single Tag’s data when it reports its position.
    • onTagLeave(tag): an optional callback function called with a single Tag data when it exits its current floor.
    • onClose(): an optional callback function called when the stream is closed.
    • onException(): an optional callback function called when the stream reports an error.

Returns an API object with the following properties:

  • close(): a method to close the stream.

Web SDK Theming

Meridian Web SDK theming is done with Cascading Style Sheets (CSS).

Meridian external hook CSS classes are prefixed with meridian-.

Styles prefixed with meridian--private-- are minified internal styles that you shouldn’t use.

Given the complexity of CSS style interactions, Meridian can’t guarantee style customizations won’t be affected between minor version upgrades, but we’ll make an effort to keep the external CSS hooks available for any necessary minor style tweaks.

Target All Maps

To target all Meridian maps on one page, you’ll want to use something like:

body .meridian-map-container {
  border: 1px solid black;
}

Target a Specific Map

To target a specific map, you can put a CSS class on the container element and target that:

.my-map .meridian-map-container {
  border: 2px solid gray;
}

Alter Backgrounds and Borders

To alter background and border styles, use .meridian-map-background and .meridian-map-container.

Target Map Buttons

You can also style the top level and floor name buttons.

Style Placemarks

You can style placemarks by placemark type using .meridian-placemark-type-{placemark type name}.

Style Tags

You can style Tags with specific labels using .meridian-tag-label-{label name}.

(function() { function $$(selector) { return [].slice.call(document.querySelectorAll(selector)); } var userInputPattern = /.insert.*here./i; $$("pre .s2").forEach(function(elem) { if (userInputPattern.test(elem.textContent)) { elem.classList.add("MeridianSDK-UserInput"); } }); })();

Related articles

Comments

0 comments

Please sign in to leave a comment.