Integration Guide

Prerequisite: Tour My App requires jQuery 1.6 or later

Before you can start running tours for your users, you need to first integrate Tour My App into your pages. Here is how you can do that.

Add these lines to the <head> section of every page that will use a tour. If you use a templating system or include system, then add it to your base template or header include.

Make sure that the code below is added after the line where you load jQuery

  <link rel="stylesheet" href="https://d345spfe4d65od.cloudfront.net/static/tourmyapp/v1/tourmyapp.css" type="text/css">
  <script type="text/javascript" src="https://d345spfe4d65od.cloudfront.net/static/tourmyapp/v1/tourmyapp.js"></script>
  
  <script type="text/javascript">
  var tour;
  jQuery(document).ready(function() {
      tour = new TourMyApp("<put_your_token_here>"); // REPLACE WITH YOUR ACCOUNT TOKEN
      tour.start();
  });
  </script>

After this code has been integrated, you are ready to start creating and running tours on your pages

Launching a tour on your site

There are many ways you can start a tour on your site. See the Tour Trigger Patterns page for more details.

Running Tour My App in Test Mode

Tour My App can be run in test mode when you are testing your tours and integrations.

In test mode:

  • The tour runs will not be counted, so you will not be using up your monthly limit
  • Analytics will not be collected, so that the actions you do while testing will not get mixed up with the analytics collected in production

Once you perform the integration, add this line just before tour.start() to enable test mode:

 tour.setOptions({"test_mode": true});

Automatically switching between test and production modes

Sometimes it is annoying to add the test mode line in development and staging servers and remove it in production server. And it is easy to forget to add or remove the line. So we highly recommend that you put a check around it to detect the server and enable test mode. Example:

  if (window.location.href.indexOf("mysite.com") == -1) {
    // Not running on mysite.com (production server), so enable test mode
    tour.setOptions({"test_mode": true});
  }

This way, the test mode will be disabled on production server and enabled otherwise

Preloading tours

Normally, when a tour is run, the tour data is downloaded from the server and then displayed on the screen. This process may lead to a short delay (usually less than a second) while the tour data is downloaded. When we know that the user is likely to trigger a particular tour on a page, we can preload the tour data so that the tour can be displayed immediately. Here is an example:

  1. The page contains a help button
  2. When the user clicks help, a tour is triggered to walk the user through the page
  3. If we preload the tour, the required data will be downloaded in the background immediately after the page loads
  4. So when the user clicks the help button, the tour is displayed immediately without needing to download the data

The way to preload a tour is to add this line just after the tour.start() line in the integration:

  tour.preload("<tour_id>");

Use the preloading feature only for cases which require a user interaction to run a tour. It is not needed for tours that are run automatically when a user visits a page. (Click here for more on different ways to trigger a tour)

Using a readable user ID for the activity stream report

The Tour My App activity stream shows a report of the steps completed by each user. To display this report, Tour My App automatically generates a random id for each user in the format user-xxxxxxxxx. The report will then display something like

  user-2393476 has started the tour.
  user-2393476 has completed step 1.
  user-2393476 has completed step 2.
  user-2393476 has completed step 3.
  user-2393476 has completed the tour.

Sometimes (especially when the user is logged in), you might want a more readable ID, such as the username or their email address.

Tour My App allows you set a specific user reference, which will be used in the activity stream report. To enable this functionality, add the following line just before tour.start():

  tour.setUserReference("<your reference here>");