How Do I Make My High Fidelity Map Interactive?

If you're familiar with JSON, you can implement interactive landmarks on the map (or background image) of your High Fidelity server.

Custom Maps

The image you see as the background of your High Fidelity server is referred to here as a "map."

You can modify your High Fidelity server URL in a specific way to encode information about your map, including the map image and clickable landmarks on the map.

To change only the map image, without adding interactivity, please use this guide.

To create and distribute interactive maps, please follow the instructions below.

Please note: Because High Fidelity is in early development, this advanced feature is subject to change without warning. 

Custom Map With Interactive Landmarks

You can place interactive landmarks on your map, such as links to your website, to a YouTube video, to a Twitch livestream.

If you are familiar with JSON, you can write and upload a JSON file, then point to that JSON file in your High Fidelity server URL using the `mapJSON` query parameter. 

Here is an example of this:

https://map.highfidelity.com/NXZL6Cx9LhsUbDBq/?mapJSON=https://highfidelity.co/speakeasyMapJSONs/mapJSONExample.json

The example JSON file referenced in the server URL above can be found here:

https://highfidelity.co/speakeasyMapJSONs/mapJSONExample.json

Map JSON File Requirements

For a custom map JSON to function, these are the rules it must follow:

  • Map JSONs must be hosted on the Internet at a publicly accessible `https://` location.
  • The host serving the Map JSON file must have CORS enabled. For more information about CORS, please go here: https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS
  • A Map JSON file must contain a valid JSON object.
  • A Map JSON file must contain the following top-level key/value pairs:
    •  `mapsJSONVersion`: A `String` containing the version of the Map JSON file. As of 2020-05-18, the latest Map JSON version is `v1.1.0`.
    • `maps`: An `Array` of Map Objects - see below.
  • A Map JSON file may contain the following top-level key/value pairs:
    •  `author`: A `String` containing the author of the Map JSON file.
    • `comments`: A `String` containing comments about the Map JSON file.
  • Map Objects must contain the following top-level key/value pairs:
    • `mapName`: A `String` containing the name of the map.
    • `mapImageSrc`: A `String` containing a URL to an image that will serve as the map background image.
      • This image should be 2048 pixels wide and 2048 pixels tall.
      • This image should be in JPG format.
      • This image should be served from an `https` host.
  •  Map Objects may contain the following top-level key/value pairs:
    • `mapLandmarks`: An `Array` of Landmark Objects - see below.

Landmarks

Map data can contain "landmarks," which are custom shapes filled with a color or an image. These shapes will appear on the map and can be clickable.

Landmark Object Requirements

  • Landmark Objects must contain the following top-level key/value pairs:
    • `name`: A `String` containing the name of the Landmark.
      • This `String` may be empty.
    • `positionSU`: An `Object` containing key/value pairs for `x`, `y`, and `z` corresponding to the coordinates of the Landmark in Speakeasy Units (meters).
      • The values associated with the above keys must be `Number`s.
      • The `z` component of `positionSU` should be `0`.
    •  `hexColor`: A `String` containing the color of the Landmark's background shape in hex.
      • This value may be seven characters in length (i.e. `#FF0000`, no alpha) or nine characters in length (i.e. `#FF0000CC`, with alpha).
    • Either `widthSU` and `heightSU` or `radiusSU`: `Number`s corresponding to the Landmark's width and height OR radius in Speakeasy Units (meters).
      • If you supply `widthSU` *AND* `heightSU`, the Landmark will be a rectangle.
      • If you supply `radiusSU`, the Landmark will be a circle.
  • Landmark Objects may contain the following top-level key/value pairs:
    • `rotationDegrees`: A `Number` corresponding to the rotation in degrees of the Landmark.
      • This value is meaningless if the Landmark is a circle
    • `href`: A `String` containing a URL. When the user clicks on this Landmark, their browser will open a new tab to this URL.
      • If you supply an `href` to a `youtube.com` or `twitch.tv` URL, the video associated with that URL will open in a picture-in-picture window in the user’s browser rather than opening in a new browser tab.
    • `imageHref`: A `String` containing a URL to an image. The image at this URL will show up as the Landmark's background.
      • If you supply `imageHref`, your Landmark must be a rectangle - i.e. you must supply `widthSU` and `heightSU`, and you must not supply `radiusSU`.
    • `textHexColor`: A `String` containing the color of the Landmark's text in hex.
      • This value may be seven characters in length (i.e. `#FF0000`, no alpha) or nine characters in length (i.e. `#FF0000CC`, with alpha).

Below is an example map containing multiple landmarks in varying styles. Clicking the maps will take you to different websites.

The JSON associated with the custom map above can be found here: https://highfidelity.co/speakeasyMapJSONs/mapJSONExample.json