Guided Tours - Cliente

  • Versão de lançamento: Xanadu
  • Atualizado 1 de ago. de 2024
  • 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.

    Guided Tours - applyListFilter(Function filter_func)

    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.

    Tabela 1. Parâmetros
    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 2. Retorna
    Tipo Descrição
    Nenhum(a)

    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()

    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.

    Tabela 3. Parâmetros
    Nome Tipo Descrição
    Nenhum
    Tabela 4. Retorna
    Tipo Descrição
    Nulo 
    //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)

    Remove um ouvinte de eventos existente.

    A assinatura completa inclui top.NOW.guided_tours.api antes do nome do método.

    Tabela 5. Parâmetros
    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
    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 6. Retorna
    Tipo Descrição
    Nenhum 
    //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)

    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.

    Tabela 7. Parâmetros
    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
    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>'}
    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)

    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)

    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.

    Tabela 8. Parâmetros
    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 9. Retorna
    Tipo Descrição
    Nenhum 
    //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()

    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()
    Tabela 10. Parâmetros
    Nome Tipo Descrição
    Nenhum
    Tabela 11. Retorna
    Tipo Descrição
    Nenhum

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

    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.

    Tabela 12. Parâmetros
    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 13. Retorna
    Tipo Descrição
    Nenhum 
    //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);