Guided Tours - Client

  • Release version: Zurich
  • Updated July 31, 2025
  • 5 minutes to read

    • The Guided Tours API provides methods for launching and stopping guided tours.

    This API includes methods used in Guided Tour Designer.

    Guided Tours - applyListFilter(Function filter_func)

    Sets a function to retrieve filtered tour results when the getAllTours() method is called.

    Complete signature includes top.NOW.guided_tours.api preceding the method name.

    Table 1. Parameters
    Name Type Description
    filter_func Function Filter function that takes a single tour object from the tours[] array returned from getAllTours() method.
    Table 2. Returns
    Type Description
    None

    The following example shows basic API usage.

    //create a filter function
var filtFunction = function(tour) {
   //only return those tours whose name starts with 'my'
   return tour.name.indexOf('my') === 0);
}

//apply the filter 
top.NOW.guided_tours.api.applyListFilter (filtFunction);

//call the getAllTours method to observe the filtered tours
top.NOW.guided_tours.api.getAllTours (function(er, tours) {
  if(!er) {
    console.log('The filtered tours are: ');
    console.log(tours);
  }
});

    The following example shows how to use the options field on the tour object to add JSON with custom tour identifiers for reading and filtering tours inside the filter_func() function.

    top.NOW.guided_tours.api.applyListFilter(function(tour) {
       var options = (tour.options)? JSON.parse(tour.options): null;
       return (options && options.my_param) ? (options.my_param == my_value) : false;
});

    Guided Tours - endTour()

    Stops a currently playing tour. This method silently exits if no tours are playing.

    Complete signature includes top.NOW.guided_tours.api preceding the method name.

    Table 3. Parameters
    Name Type Description
    None
    Table 4. Returns
    Type Description
    Null 
    //create a callback function to end the tour if it starts correctly
var cbFunction = function(err) {
	if (err) {
   console.log('Error Occurred');
}
	else {
	   // tour has started so we can call endTour
	   top.NOW.guided_tours.api.endTour();
}
}

//calling the startTour method so that we can end the tour as soon as it starts
top.NOW.guided_tours.api.startTour('a297e04b732313007077edcc5ef6a780', 2, cbFunction);

    Guided Tours - events.off(String event_name, Function listener_function)

    Removes an existing event listener.

    Complete signature includes top.NOW.guided_tours.api preceding the method name.

    Table 5. Parameters
    Name Type Description
    event_name String Event name to be removed from the listener.
    Valid event names:
    • tourStarted
    • tourEnded
    • tourCompleted
    • tourFailed
    • tourAbandoned
    • tourDismissed
    • stepStarted
    listener_function Function Optional. If provided, specified listener function is removed from remaining event listeners attached with that event. If not provided, all listener functions attached to that event are removed.
    Table 6. Returns
    Type Description
    None 
    //create a callback function to handle the result of the api call
var eventListenerTourStarted = function() {
   console.log('The tour has started'); 
}
var eventListenerTourEnded = function() {
   console.log('The tour has ended'); 
}

//attaching event listeners for tourStarted and tourEnded Events
top.NOW.guided_tours.events.on('tourStarted',eventListenerTourStarted);
top.NOW.guided_tours.events.on('tourEnded', eventListenerTourEnded);

…
//start a tour
top.NOW.guided_tours.api.startTour ('a297e04b732313007077edcc5ef6a780', 2, cbFunction);
//As soon as the tour starts the eventListenerTourStarted gets fired
…
top.NOW.guided_tours.api.endTour();
// eventListenerTourEnded gets fired

….

//removing the event listeners top.NOW.guided_tours.events.off('tourStarted',eventListenerTourStarted);
top.NOW.guided_tours.events.off('tourEnded', eventListenerTourEnded);

    Guided Tours - events.on(String event_name, Function listener_function)

    Attaches an event listener to a guided tour event.

    Complete signature includes top.NOW.guided_tours.api preceding the method name.

    Table 7. Parameters
    Name Type Description
    event_name String Event name to be attached to the listener.
    Valid event names:
    • stepStarted
    • tourStarted
    • tourEnded
    • tourCompleted
    • tourFailed
    • tourAbandoned
    • tourDismissed
    listener_function Function Listener to be added.
    Note:
    Clear any event listener after it solves its purpose.
    listener_function.obj Object Passed to listener_function() by each event in the following format:
    • For stepStarted events: 
      {tour: '<tour_sys_id>', step: step_num}
    • For all other events:
      {tour: '<tour_sys_id>'}
    JSON parameters:
    • tour_sys_id: String. Guided tour ID from the Guided Tours [sys_embedded_tour_guide] table
    • step_num: Number. Value between 0 (first step) and n (final step)

    The following example shows basic API usage.

    //create a callback function to handle the result of the api call
var eventListenerTourStarted = function() {
   console.log('The tour has started'); 
}
var eventListenerTourEnded = function() {
   console.log('The tour has ended'); 
}

//attaching event listeners for tourStarted and tourEnded Events
top.NOW.guided_tours.events.on('tourStarted',eventListenerTourStarted);
top.NOW.guided_tours.events.on('tourEnded', eventListenerTourEnded);

…
//start a tour
top.NOW.guided_tours.api.startTour ('a297e04b732313007077edcc5ef6a780', 2, cbFunction);
//As soon as the tour starts the eventListenerTourStarted gets fired
…
top.NOW.guided_tours.api.endTour();
// eventListenerTourEnded gets fired

….

//removing the event listeners top.NOW.guided_tours.events.off('tourStarted',eventListenerTourStarted);
top.NOW.guided_tours.events.off('tourEnded', eventListenerTourEnded);

    The following example shows how to use the listener_function parameter with obj as an argument.

    top.NOW.guided_tours.events.on("tourStarted", function (obj){console.log(obj);});

    Guided Tours - getAllTours(Function cb_function)

    Gets a list of tours on the current page from which this method is called. Because this method is asynchronous, a callback function must be passed to determine operation success and get a list of tours.

    Complete signature includes top.NOW.guided_tours.api preceding the method name.

    Table 8. Parameters
    Name Type Description
    cb_function Function Callback function called by getAllTours() after attempt to fetch all tours for the current page from which getAllTours() method is called.
    cb_function.err Object Points to the error object if any occurred during the operation:

    err = { success: false, message: 'string containing the error object' }

    Null otherwise.
    cb_function.tours Array List of available tours for the page.

    If no tours are present on the page, cb_function.tours returns undefined.

    if(!tours) console.log('No tour present')
    Table 9. Returns
    Type Description
    None 
    //create a callback function to handle the result of the API call
var cbFunction = function(err, tours) {
	if (err) {
   console.log('Error Occurred');
}
	else {
	    if(!tours) console.log('No tour present')
   else {
      tours.forEach(function(t) {
               console.log(t);
             });
          }
}
}
//calling the getTours method
top.NOW.guided_tours.api.getAllTours(cbFunction);

    Guided Tours - loadPlayer()

    Loads the guided tours player on a page in which guided tours player is not present by default.

    Complete signature: 
    NOW.guided_tours.api.loadPlayer()
    Table 10. Parameters
    Name Type Description
    None
    Table 11. Returns
    Type Description
    None

    Guided Tours - startTour(String tour_id, Number step_number, Function cb_function)

    Starts a tour. Because this method is asynchronous, you must pass a callback function to determine operation success.

    Complete signature includes top.NOW.guided_tours.api preceding the method name.

    Table 12. Parameters
    Name Type Description
    tour_id String Sys ID of the tour from the Guided Tours [sys_embedded_tour_guide] table.
    step_number Number Optional. Step at which to start the tour. If not provided (or step number is 0), tour starts from the beginning.
    cb_function Function Optional. Callback function called by startTour() method after attempt to launch the tour.
    cb_function.err Object Points to the error object if any occurred during the operation:

    err = { success: false, message: 'string containing the error object' }

    Null otherwise.
    Table 13. Returns
    Type Description
    None 
    //create a callback function to handle the result of the API call
var cbFunction = function(err) {
	if (err) {
   console.log('Error Occurred');
}
	else {
   console.log('The tour with tourid=%s was successfully launched', tourId);
}
}

//calling the startTour method
top.NOW.guided_tours.api.startTour('a297e04b732313007077edcc5ef6a780', 2, cbFunction);