Viewer API

Control an embedded TeliportMe virtual tour from your own web page. Read the camera heading as visitors look around, react to pano changes and hotspot clicks, and move the view from your own buttons, maps or compasses.

Quick start

Add the API script to your page, embed your tour with the /embed/tour/ URL, and listen for events.

<script src="https://teliportme.com/js/api.js"></script>

<iframe
  src="https://teliportme.com/embed/tour/YOUR_TOUR_ID"
  width="100%"
  height="600"
  frameborder="0"
  allowfullscreen
  allow="vr;gyroscope;accelerometer;fullscreen;"
></iframe>

<script>
  TeliportmeViewerAPI.addEventListener('tourready', function (e) {
    console.log('Tour loaded', e.data.tour.title, e.data.panos);
  });
  TeliportmeViewerAPI.addEventListener('orientationchange', function (e) {
    console.log('Heading', e.data.heading);
  });
</script>

You can also use the JavaScript embed code from the tour's Share dialog; it works with the API the same way.

Use the /embed/tour/… link, not the /virtualtour/… page link. The API matches each tour to its iframe using the iframe's src, so the src must load directly, without redirecting to another URL.

Multiple tours on one page

Every event includes e.frame, an id for the iframe that sent it. Pass it as the first argument to any method so the command goes to the right tour. Keep it from tourready:

var frame;
TeliportmeViewerAPI.addEventListener('tourready', function (e) {
  frame = e.frame;
});
// later
TeliportmeViewerAPI.setPano(frame, 2);

Events

Subscribe with TeliportmeViewerAPI.addEventListener(name, callback) and unsubscribe with removeEventListener(name, callback). The callback receives { frame, data }.

tourready

Fired once the tour has loaded. Also includes e.element, the iframe element.

{
  tour: { title, description, lat, lng },
  panos: [
    { id, title, description, thumbnail, lat, lng },
    ...
  ]
}

panos[i].id is the pano's position in the tour (starting at 0) and is the value setPano takes.

panoready

Fired each time a pano finishes loading.

{ id, title, description, thumbnail, lat, lng }

orientationchange

Fired continuously while the view moves (drag, gyroscope, auto-rotate or API calls).

hotspotclick

Fired when a visitor clicks a hotspot.

{ id, panoid, type }

type is the hotspot type, for example pano, image, video, popup or link.

fullscreenchange

Fired when the viewer enters or leaves fullscreen.

{ fullscreen: true | false }

Methods

North calibration

Each pano has its own north setting. In the tour editor, open a pano, go to North Point, turn the view to face north and save. Repeat for every pano that needs it.

heading and setHeading use this calibration. For a pano without one, north is the centre of the panorama image, so heading equals yaw.

Example: 8-direction compass

<script src="https://teliportme.com/js/api.js"></script>
<iframe src="https://teliportme.com/embed/tour/YOUR_TOUR_ID" width="100%" height="600"
  frameborder="0" allowfullscreen allow="vr;gyroscope;accelerometer;fullscreen;"></iframe>
<div id="compass">N 0°</div>
<img id="needle" src="needle.svg" width="80" height="80" alt="" />

<script>
  var directions = ['N', 'NE', 'E', 'SE', 'S', 'SW', 'W', 'NW'];
  var frame;

  TeliportmeViewerAPI.addEventListener('tourready', function (e) {
    frame = e.frame;
  });

  TeliportmeViewerAPI.addEventListener('orientationchange', function (e) {
    var heading = e.data.heading;
    document.getElementById('compass').textContent =
      directions[Math.round(heading / 45) % 8] + ' ' + Math.round(heading) % 360 + '°';
    // Rotate a north-pointing needle against the heading
    document.getElementById('needle').style.transform = 'rotate(' + -heading + 'deg)';
  });

  // Turn the view to face east
  function faceEast() {
    TeliportmeViewerAPI.setHeading(frame, 90);
  }
</script>

A complete version with a clickable compass rose is at /skin/compass. View its source to copy it.

Raw postMessage protocol

api.js is a thin wrapper around window.postMessage. If you'd rather not include it, you can talk to the iframe directly.

The viewer sends messages to its parent page in this shape:

{
  teliportme: true,
  uuid: '…',   // id of this viewer; send it back with commands
  cmd: 'orientationchange',   // the event name
  src: 'https://teliportme.com/embed/tour/…',
  data: { heading, yaw, pitch, zoom }
}

Commands are sent to the iframe's window:

window.addEventListener('message', function (e) {
  if (e.origin !== 'https://teliportme.com' || !e.data || !e.data.teliportme) return;
  if (e.data.cmd === 'orientationchange') {
    console.log(e.data.data.heading);
  }
  if (e.data.cmd === 'tourready') {
    // Face east
    iframe.contentWindow.postMessage(
      { teliportme: true, uuid: e.data.uuid, cmd: 'setheading', value: 90 },
      'https://teliportme.com'
    );
  }
});

Command names are setpano (with id), setheading, setpitch, setzoom, setautorotate (each with value) and fullscreen.

Live examples

• API demo: pano list, hotspot events, heading/pitch/zoom readout and controls.
• Compass skin: 8-direction compass synced to the camera heading.
• Map skin: tour beside a map of its pano locations.

Questions? Contact us.