---
sourceDocument: Referência de API do Xanadu
sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/pt-BR/xanadu/api-reference

 Release :

    - xanadu

ft:locale :

    - pt-BR

ft:publication_title :

    - Referência de API do Xanadu

ft:clusterId :

    - crapiref

bundleId :

    - crapiref

workflow :

    - Creator


---

# Guided Tours - Cliente

# Guided Tours - Cliente {#ariaid-title1}

* Versão de lançamento: Xanadu
* 
* Atualizado 1 de ago. de 2024
* 
* ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 5 min. de leitura

A API Guided Tours fornece métodos para iniciar e parar tours guiados.

Esta API inclui métodos usados no [Guided Tour Designer](https://servicenow-prod.fluidtopics.net/pX3f_EMUubT1Oubo5CfZ3w "As mensagens REST enviadas para uma instância retornam um código de resposta HTTP específico.").

## Guided Tours - applyListFilter(Function filter_func) {#ariaid-title2}

Define uma função para recuperar resultados de tour filtrados quando o método `getAllTours()` é chamado.
A assinatura completa inclui `top.NOW.guided_tours.api` antes do nome do método.
{#GT-applyListFilter_F__table_pqn_dbs_xhb__entry__3}

| Nome | Tipo | Descrição |
|-|-|-|
| filter_func | Função | Função de filtro que obtém um único objeto de `tour` da matriz `tours[]` retornada do método `getAllTours()`. |
[Tabela 1. Parâmetros]

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

| Tipo | Descrição |
|-|-|
| Nenhum(a) |   |
[Tabela 2. Retorna]

{#GT-applyListFilter_F__table_qqn_dbs_xhb}  
O exemplo a seguir mostra o uso básico da 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);
      }
    });

O exemplo a seguir mostra como usar o campo de `opções` no objeto de tour para adicionar JSON com identificadores de tour personalizados para ler e filtrar tours dentro da função `filter_func()`.

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

## Tours guiados - endTour() {#ariaid-title3}

Interrompe um tour em reprodução. Este método será encerrado silenciosamente se nenhum tour estiver sendo reproduzido.
A assinatura completa inclui `top.NOW.guided_tours.api` antes do nome do método.
{#GT-endTour__table_g5n_3cs_xhb__entry__3}

| Nome | Tipo | Descrição |
|-|-|-|
| Nenhum |   |   |
[Tabela 3. Parâmetros]

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

| Tipo | Descrição |
|-|-|
| Nulo |   |
[Tabela 4. Retorna]

{#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);

## Guided Tours - eventos.off(cadeia de caracteres event_name, função ouvinte_function) {#ariaid-title4}

Remove um ouvinte de eventos existente.
A assinatura completa inclui `top.NOW.guided_tours.api` antes do nome do método.
{#GT-events.off_S_F__table_iwb_kbs_xhb__entry__3}

| Nome | Tipo | Descrição |
|-|-|-|
| event_name | Cadeia de caracteres | Nome do evento a ser removido do ouvinte. Nomes de evento válidos: * tourIniciado * tourEnded * tourConcluído * tourFalha * tourAbandonado * tourDispensado * etapaIniciada {#GT-events.off_S_F__ul_tn1_x4t_yhb} |
| função_ouvinte | Função | Opcional. Se fornecido, a função de ouvinte especificada será removida dos ouvintes de eventos restantes anexados a esse evento. Se não for fornecido, todas as funções de ouvinte anexadas a esse evento serão removidas. |
[Tabela 5. Parâmetros]

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

| Tipo | Descrição |
|-|-|
| Nenhum |   |
[Tabela 6. Retorna]

{#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);

## Guided Tours - eventos.on(cadeia de caracteres event_name, função ouvinte_function) {#ariaid-title5}

Anexa um ouvinte de eventos a um evento de tour guiado.
A assinatura completa inclui `top.NOW.guided_tours.api` antes do nome do método.
{#GT-events.on_S_F__table_iwb_kbs_xhb__entry__3}

| Nome | Tipo | Descrição |
|-|-|-|
| event_name | Cadeia de caracteres | Nome do evento a ser anexado ao ouvinte. Nomes de evento válidos: * etapaIniciada * tourIniciado * tourEnded * tourConcluído * tourFalha * tourAbandonado * tourDispensado {#GT-events.on_S_F__ul_tn1_x4t_yhb} |
| função_ouvinte | Função | Ouvinte a ser adicionado. Nota: Limpe qualquer ouvinte de evento depois que ele resolver sua finalidade. |
| listener_function.obj | Objeto | Passado para `ouvinte_function()` por cada evento no seguinte formato: * Para eventos stepStarted: {tour: '<tour_sys_id>', step: step_num} * Para todos os outros eventos: {tour: '<tour_sys_id>'} {#GT-events.on_S_F__ul_wsr_khs_g3b} Parâmetros JSON: * tour_sys_id: cadeia de caracteres. ID do tour guiado da tabela Guided Tours \[sys_embedded_tour_guide\] * step_num: número. Valor entre 0 (primeira etapa) e `n` (etapa final) {#GT-events.on_S_F__ul_qfx_nhs_g3b} |
[Tabela 7. Parâmetros]

{#GT-events.on_S_F__table_iwb_kbs_xhb}  
O exemplo a seguir mostra o uso básico da 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);

O exemplo a seguir mostra como usar o parâmetro `listener_function` com `obj` como um argumento.

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

## Tours guiados - getAllTours(Function cb_function) {#ariaid-title6}

Obtém uma lista de tours na página atual da qual este método é chamado. Como este método é assíncrono, uma função de retorno de chamada deve ser aprovada para determinar o sucesso da operação e obter uma lista de tours.
A assinatura completa inclui `top.NOW.guided_tours.api` antes do nome do método.
{#GT-getAllTours_F__table_nrj_bbs_xhb__entry__3}

| Nome | Tipo | Descrição |
|-|-|-|
| função_cb | Função | Função de retorno de chamada chamada por `getAllTours()` após a tentativa de buscar todos os tours da página atual na qual o método `getAllTours()` é chamado. |
| cb_function.err | Objeto | Aponta para o objeto de erro se ocorreu algum durante a operação: `erro = { sucesso: falso, mensagem: 'cadeia de caracteres que contém o objeto de erro' }` Caso contrário, nulo. |
| cb_function.tours | Matriz | Lista de tours disponíveis para a página. Se nenhum tour estiver presente na página, `cb_function.tours` retornará indefinido. `if(!tours) console.log('Nenhum tour presente')` |
[Tabela 8. Parâmetros]

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

| Tipo | Descrição |
|-|-|
| Nenhum |   |
[Tabela 9. Retorna]

{#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);

## Tours guiados - loadPlayer() {#ariaid-title7}

Carrega o reprodutor de tours guiados em uma página na qual o reprodutor de tours guiados não está presente por padrão.
Assinatura completa:

    NOW.guided_tours.api.loadPlayer()

{#GT-loadPlayer__table_g5n_3cs_xhb__entry__3}

| Nome | Tipo | Descrição |
|-|-|-|
| Nenhum |   |   |
[Tabela 10. Parâmetros]

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

| Tipo | Descrição |
|-|-|
| Nenhum |   |
[Tabela 11. Retorna]

{#GT-loadPlayer__table_h5n_3cs_xhb}

## Guided Tours - startTour(cadeia de caracteres tour_id, número step_number, função cb_function) {#ariaid-title8}

Inicia um tour. Como este método é assíncrono, você deve passar uma função de retorno de chamada para determinar o sucesso da operação.
A assinatura completa inclui `top.NOW.guided_tours.api` antes do nome do método.
{#GT-startTour_S_N_F__table_wh5_w1s_xhb__entry__3}

| Nome | Tipo | Descrição |
|-|-|-|
| tour_id | Cadeia de caracteres | SYS ID do tour da tabela Guided Tours \[sys_embedded_tour_guide\]. |
| número_de_etapa | Número | Opcional. Etapa na qual o tour é iniciado. Se não for fornecido (ou o número da etapa for 0), o tour começará do início. |
| função_cb | Função | Opcional. Função de retorno de chamada chamada pelo método `startTour()` após a tentativa de iniciar o tour. |
| cb_function.err | Objeto | Aponta para o objeto de erro se ocorreu algum durante a operação: `erro = { sucesso: falso, mensagem: 'cadeia de caracteres que contém o objeto de erro' }` Caso contrário, nulo. |
[Tabela 12. Parâmetros]

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

| Tipo | Descrição |
|-|-|
| Nenhum |   |
[Tabela 13. Retorna]

{#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);