How Do I Make My High Fidelity Background Map Interactive?

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

Custom Maps

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

You can modify your High Fidelity space's 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 space's URL using the `mapJSON` query parameter. 

Here is an example of this:

https://map.highfidelity.com/NXZL6Cx9LhsUbDBq/?mapJSON=https://hifi-json.s3.amazonaws.com/mapJSONExample.json

(Please note that the above URL is syntactically correct but does not go to a real High Fidelity space.)

The example JSON file referenced in the space's URL above can be found here:

https://hifi-json.s3.amazonaws.com/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.
      • NOTE: For picture-in-picture to work with YouTube, the YouTube link format must be the long, direct link to the video. To obtain this, navigate to the video you want to embed on YouTube (not in a playlist or a channel), and copy the URL from your browser bar. Shortened links with "youtu.be", and links from a channel or playlist, will not allow picture-in-picture, and instead will open in another tab.
    • `autoplay`: If `autoplay` is `true`, the YouTube or Twitch video associated with that landmark will auto-play.
      • Only one landmark associated with a given map can have `autoplay: true`.
    • `audioOnly`: If `audioOnly` is `true`, the YouTube video associated with that landmark will not be displayed.
      • Only YouTube videos support `audioOnly`.
    • `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.

High Fidelity map with Landmark circles and rectangles accompanying with text on top of the shapes.

The JSON associated with the custom map above can be found here: https://hifi-json.s3.amazonaws.com/mapJSONExample.json