가이드 투어 - 클라이언트

  • 릴리스 버전: Yokohama
  • 업데이트 날짜 2025년 01월 30일
  • 읽기11분

    • Guided Tours API는 가이드가 있는 둘러보기를 시작하고 중지하는 메서드를 제공합니다.

    이 API에는 가이드 투어 디자이너에 사용되는 메서드가 포함됩니다.

    가이드 투어 - applyListFilter(Function filter_func)

    getAllTours() 메서드가 호출될 때 필터링된 둘러보기 결과를 검색하는 함수를 설정합니다.

    완전한 서명에는 상단이 포함됩니다. NOW.guided_tours.API 를 사용합니다.

    표 1. 매개변수
    이름 유형 설명
    filter_func 함수 getAllTours() 메서드에서 반환된 tours[] 배열에서 단일 둘러보기 객체를 가져오는 필터 함수입니다.
    표 2. 반환
    유형 설명
    안 함

    다음 예제에서는 기본 API 사용법을 보여 줍니다.

    //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);
  }
});

    다음 예제에서는 tour 개체의 options 필드를 사용하여 filter_func() 함수 내에서 둘러보기를 읽고 필터링하기 위한 사용자 지정 둘러보기 식별자가 있는 JSON을 추가하는 방법을 보여 줍니다.

    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;
});

    가이드 투어 - endTour()

    현재 재생 중인 둘러보기를 중지합니다. 이 메서드는 재생 중인 둘러보기가 없으면 자동으로 종료됩니다.

    완전한 서명에는 상단이 포함됩니다. NOW.guided_tours.API 를 사용합니다.

    표 3. 매개변수
    이름 유형 설명
    없음
    표 4. 반환
    유형 설명
    영 
    //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);

    가이드 투어 - events.off(String event_name, Function listener_function)

    기존 이벤트 수신기를 제거합니다.

    완전한 서명에는 상단이 포함됩니다. NOW.guided_tours.API 를 사용합니다.

    표 5. 매개변수
    이름 유형 설명
    event_name 문자열 수신기에서 제거할 이벤트 이름입니다.
    유효한 이벤트 이름:
    • tourStarted
    • tourEnded
    • 투어완료됨
    • tourFailed
    • 투어포기됨
    • tour해제됨
    • stepStarted
    listener_function 함수 옵션입니다. 제공된 경우 지정된 수신기 함수는 해당 이벤트와 연결된 나머지 이벤트 수신기에서 제거됩니다. 제공되지 않은 경우 해당 이벤트에 연결된 모든 수신기 함수가 제거됩니다.
    표 6. 반환
    유형 설명
    안 함 
    //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);

    가이드 투어 - events.on(String event_name, Function listener_function)

    이벤트 수신기를 가이드가 있는 둘러보기 이벤트에 연결합니다.

    완전한 서명에는 상단이 포함됩니다. NOW.guided_tours.API 를 사용합니다.

    표 7. 매개변수
    이름 유형 설명
    event_name 문자열 수신기에 연결할 이벤트 이름입니다.
    유효한 이벤트 이름:
    • stepStarted
    • tourStarted
    • tourEnded
    • 투어완료됨
    • tourFailed
    • 투어포기됨
    • tour해제됨
    listener_function 함수 추가할 수신기입니다.
    주:
    목적을 해결한 후 이벤트 수신기를 지웁니다.
    listener_function.obj 객체 다음 형식으로 각 이벤트에 의해 listener_function() 에 전달됩니다.
    • stepStarted 이벤트의 경우: 
      {tour: '<tour_sys_id>', step: step_num}
    • 다른 모든 이벤트의 경우:
      {tour: '<tour_sys_id>'}
    JSON 매개변수:
    • tour_sys_id: 문자열. 가이드가 있는 둘러보기 [sys_embedded_tour_guide] 테이블의 가이드가 있는 둘러보기 ID
    • step_num: 숫자. 0(첫 번째 단계)과 n (최종 단계) 사이의 값

    다음 예제에서는 기본 API 사용법을 보여 줍니다.

    //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);

    다음 예제에서는 obj를 인수로 사용하여 listener_function 매개 변수를 사용하는 방법을 보여 줍니다.

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

    가이드 투어 - getAllTours(기능 cb_function)

    이 메서드가 호출되는 현재 페이지의 둘러보기 목록을 가져옵니다. 이 메서드는 비동기식이므로 작업 성공 여부를 확인하고 둘러보기 목록을 가져오려면 콜백 함수를 전달해야 합니다.

    완전한 서명에는 상단이 포함됩니다. NOW.guided_tours.API 를 사용합니다.

    표 8. 매개변수
    이름 유형 설명
    cb_function 함수 getAllTours() 메서드가 호출된 현재 페이지에 대한 모든 둘러보기를 가져오려고 시도한 후 getAllTours()에서 호출한 콜백 함수입니다.
    cb_function.err 객체 작업 중에 발생한 오류 객체를 가리킵니다.

    err = { 성공: false, 메시지: '오류 객체가 포함된 문자열' }

    그렇지 않으면 Null입니다.
    cb_function.tours 배열 페이지에 사용할 수 있는 둘러보기 목록입니다.

    페이지에 둘러보기가 없는 경우 cb_function.tours 는 undefined를 반환합니다.

    if(!tours) console.log('둘러보기 없음')
    표 9. 반환
    유형 설명
    안 함 
    //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);

    가이드 투어 - loadPlayer()

    기본적으로 가이드 투어 플레이어가 없는 페이지에 가이드 투어 플레이어를 로드합니다.

    서명 완료: 
    NOW.guided_tours.api.loadPlayer()
    표 10. 매개변수
    이름 유형 설명
    없음
    표 11. 반환
    유형 설명
    안 함

    가이드 투어 - startTour(String tour_id, Number step_number, Function cb_function)

    둘러보기를 시작합니다. 이 메서드는 비동기적이므로 콜백 함수를 전달하여 작업 성공을 확인해야 합니다.

    완전한 서명에는 상단이 포함됩니다. NOW.guided_tours.API 를 사용합니다.

    표 12. 매개변수
    이름 유형 설명
    tour_id 문자열 가이드 투어 [sys_embedded_tour_guide] 테이블의 둘러보기 시스템 ID입니다.
    step_number 번호 옵션입니다. 둘러보기를 시작할 단계입니다. 입력하지 않거나 단계 번호가 0인 경우 둘러보기가 처음부터 시작됩니다.
    cb_function 함수 옵션입니다. 둘러보기 시작을 시도한 후 startTour() 메서드에서 호출하는 콜백 함수입니다.
    cb_function.err 객체 작업 중에 발생한 오류 객체를 가리킵니다.

    err = { 성공: false, 메시지: '오류 객체가 포함된 문자열' }

    그렇지 않으면 Null입니다.
    표 13. 반환
    유형 설명
    안 함 
    //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);