---
sourceDocument: 호주 API 참조
sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/ko-KR/api-reference

 Release :

    - australia

ft:locale :

    - ko-KR

ft:publication_title :

    - 호주 API 참조

ft:clusterId :

    - crapiref

bundleId :

    - crapiref

workflow :

    - Creator


---

# 가이드 투어 - 클라이언트

# 가이드 투어 - 클라이언트 {#ariaid-title1}

* 릴리스 버전: Australia
* 
* 업데이트 날짜 2026년 03월 12일
* 
* ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 소요 시간: 11분

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

이 API에는 [가이드 투어 디자이너](https://servicenow-prod.fluidtopics.net/CNd5LBNMHVFFJxr3SxZDjw "인스턴스로 전송된 REST 메시지는 특정 HTTP 응답 코드를 반환합니다.")에서 사용되는 메서드가 포함되어 있습니다.

## 가이드 투어 - applyListFilter(함수 filter_func) {#ariaid-title2}

`getAllTours()` 메서드가 호출될 때 필터링된 둘러보기 결과를 검색하도록 함수를 설정합니다.
전체 서명에는 상단이 포함됩니다 `. NOW.guided_tours.api` 를 메서드 이름 앞에 추가합니다.
{#GT-applyListFilter_F__table_pqn_dbs_xhb__entry__3}

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

{#GT-applyListFilter_F__table_pqn_dbs_xhb} {#GT-applyListFilter_F__table_qqn_dbs_xhb__entry__2}

| 유형 | 설명 |
|-|-|
| 없음 |   |
[표 2. 반환]

{#GT-applyListFilter_F__table_qqn_dbs_xhb}  
다음 예는 기본 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);
      }
    });

다음 예제는 둘러보기 객체의 `옵션` 필드를 사용하여 `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() {#ariaid-title3}

현재 진행 중인 둘러보기를 중지합니다. 이 메서드는 재생 중인 둘러보기가 없는 경우 자동으로 종료됩니다.
전체 서명에는 상단이 포함됩니다 `. NOW.guided_tours.api` 를 메서드 이름 앞에 추가합니다.
{#GT-endTour__table_g5n_3cs_xhb__entry__3}

| 이름 | 유형 | 설명 |
|-|-|-|
| 안 함 |   |   |
[표 3. 매개변수]

{#GT-endTour__table_g5n_3cs_xhb} {#GT-endTour__table_h5n_3cs_xhb__entry__2}

| 유형 | 설명 |
|-|-|
| null |   |
[표 4. 반환]

{#GT-endTour__table_h5n_3cs_xhb}  

    //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(문자열 event_name, 함수 listener_function) {#ariaid-title4}

기존 이벤트 수신기를 제거합니다.
전체 서명에는 상단이 포함됩니다 `. NOW.guided_tours.api` 를 메서드 이름 앞에 추가합니다.
{#GT-events.off_S_F__table_iwb_kbs_xhb__entry__3}

| 이름 | 유형 | 설명 |
|-|-|-|
| event_name | 문자열 | 수신기에서 제거할 이벤트 이름입니다. 유효한 이벤트 이름: * tourStarted * tourEnded * tour완료됨 * tourFailed * tour포기됨 * 둘러보기 해제됨 * stepStarted {#GT-events.off_S_F__ul_tn1_x4t_yhb} |
| listener_function | 함수 | 옵션입니다. 제공된 경우, 지정된 수신기 함수는 해당 이벤트에 연결된 나머지 이벤트 수신기에서 제거됩니다. 제공되지 않은 경우 해당 이벤트에 연결된 모든 수신기 기능이 제거됩니다. |
[표 5. 매개변수]

{#GT-events.off_S_F__table_iwb_kbs_xhb} {#GT-events.off_S_F__table_jwb_kbs_xhb__entry__2}

| 유형 | 설명 |
|-|-|
| 안 함 |   |
[표 6. 반환]

{#GT-events.off_S_F__table_jwb_kbs_xhb}  

    //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(문자열 event_name, 함수 listener_function) {#ariaid-title5}

가이드가 있는 둘러보기 이벤트에 이벤트 수신기를 연결합니다.
전체 서명에는 상단이 포함됩니다 `. NOW.guided_tours.api` 를 메서드 이름 앞에 추가합니다.
{#GT-events.on_S_F__table_iwb_kbs_xhb__entry__3}

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

{#GT-events.on_S_F__table_iwb_kbs_xhb}  
다음 예는 기본 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) {#ariaid-title6}

이 메서드가 호출된 현재 페이지에서 둘러보기 목록을 가져옵니다. 이 메서드는 비동기식이므로 작업 성공 여부를 확인하고 둘러보기 목록을 가져오려면 콜백 함수를 전달해야 합니다.
전체 서명에는 상단이 포함됩니다 `. NOW.guided_tours.api` 를 메서드 이름 앞에 추가합니다.
{#GT-getAllTours_F__table_nrj_bbs_xhb__entry__3}

| 이름 | 유형 | 설명 |
|-|-|-|
| cb_function | 함수 | `getAllTours()` 메서드가 호출된 현재 페이지의 모든 둘러보기를 가져오려고 시도한 후 `getAllTours()`에서 호출된 콜백 함수입니다. |
| cb_function.err | 객체 | 작업 중에 오류가 발생할 경우 오류 객체를 가리킵니다. `err = { 성공: 아니오, 메시지: '오류 객체를 포함하는 문자열' }` 그렇지 않으면 null입니다. |
| cb_function.tours | 배열 | 페이지에서 사용 가능한 둘러보기 목록입니다. 페이지에 둘러보기가 없으면 `cb_function.tours가` 정의되지 않음을 반환합니다. `if(!tours) console.log('투어 없음')` |
[표 8. 매개변수]

{#GT-getAllTours_F__table_nrj_bbs_xhb} {#GT-getAllTours_F__table_orj_bbs_xhb__entry__2}

| 유형 | 설명 |
|-|-|
| 안 함 |   |
[표 9. 반환]

{#GT-getAllTours_F__table_orj_bbs_xhb}  

    //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() {#ariaid-title7}

가이드가 있는 둘러보기 플레이어가 기본적으로 없는 페이지에 가이드 투어 플레이어를 로드합니다.
서명 완료:

    NOW.guided_tours.api.loadPlayer()

{#GT-loadPlayer__table_g5n_3cs_xhb__entry__3}

| 이름 | 유형 | 설명 |
|-|-|-|
| 안 함 |   |   |
[표 10. 매개변수]

{#GT-loadPlayer__table_g5n_3cs_xhb} {#GT-loadPlayer__table_h5n_3cs_xhb__entry__2}

| 유형 | 설명 |
|-|-|
| 안 함 |   |
[표 11. 반환]

{#GT-loadPlayer__table_h5n_3cs_xhb}

## 가이드 투어 - startTour(문자열 tour_id, 번호 step_number, 함수 cb_function) {#ariaid-title8}

둘러보기를 시작합니다. 이 메서드는 비동기식이므로 작업 성공 여부를 확인하려면 콜백 함수를 전달해야 합니다.
전체 서명에는 상단이 포함됩니다 `. NOW.guided_tours.api` 를 메서드 이름 앞에 추가합니다.
{#GT-startTour_S_N_F__table_wh5_w1s_xhb__entry__3}

| 이름 | 유형 | 설명 |
|-|-|-|
| tour_id | 문자열 | 가이드 투어 \[sys_embedded_tour_guide\] 테이블의 둘러보기 시스템 ID입니다. |
| step_number | 번호 | 옵션입니다. 둘러보기를 시작할 단계입니다. 제공되지 않은 경우(또는 단계 번호가 0인 경우) 둘러보기가 처음부터 시작됩니다. |
| cb_function | 함수 | 옵션입니다. 둘러보기 시작 시도 후 `startTour()` 메서드에서 호출된 콜백 함수입니다. |
| cb_function.err | 객체 | 작업 중에 오류가 발생할 경우 오류 객체를 가리킵니다. `err = { 성공: 아니오, 메시지: '오류 객체를 포함하는 문자열' }` 그렇지 않으면 null입니다. |
[표 12. 매개변수]

{#GT-startTour_S_N_F__table_wh5_w1s_xhb} {#GT-startTour_S_N_F__table_xh5_w1s_xhb__entry__2}

| 유형 | 설명 |
|-|-|
| 안 함 |   |
[표 13. 반환]

{#GT-startTour_S_N_F__table_xh5_w1s_xhb}  

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