Guided Tours - Client

  • リリースバージョン: Australia
  • 更新日 2026年03月12日
  • 所要時間：14分

    • 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.

    表 : 1. Parameters
    Name Type Description
    filter_func Function Filter function that takes a single tour object from the tours[] array returned from getAllTours() method.
    表 : 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.

    表 : 3. Parameters
    Name Type Description
    None
    表 : 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.

    表 : 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.
    表 : 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.

    表 : 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.
    注:
    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.

    表 : 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')
    表 : 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()
    表 : 10. Parameters
    Name Type Description
    None
    表 : 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.

    表 : 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.
    表 : 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);