Логирование событий

Shepherd.js предоставляет встроенные возможности для отслеживания и логирования событий, происходящих в процессе проведения интерактивных туров. Каждый тур и каждый шаг сопровождаются рядом событий, которые можно использовать для анализа поведения пользователя, отладки или интеграции с внешними системами аналитики.

Логирование событий строится вокруг подписки на события через методы on, once и off. Эти методы позволяют регистрировать обработчики, которые срабатывают при возникновении определённых событий.

const tour = new Shepherd.Tour({
  defaultStepOptions: {
    scrollTo: true
  }
});

// Подписка на событие начала тура
tour.on('start', () => {
  console.log('Тур начался');
});

// Подписка на событие окончания тура
tour.on('complete', () => {
  console.log('Тур завершён');
});

// Подписка на завершение конкретного шага
tour.on('show', (event) => {
  console.log(`Показан шаг: ${event.step.id}`);
});

Ключевые события Shepherd.js

Shepherd.js предоставляет множество событий, которые можно использовать для детального логирования:

  • start – срабатывает при запуске тура.
  • complete – фиксирует завершение тура пользователем.
  • cancel – срабатывает, если тур был прерван до завершения.
  • show – срабатывает при показе каждого шага. Объект события содержит ссылку на текущий шаг (event.step).
  • hide – срабатывает при скрытии шага.
  • active – фиксирует момент, когда шаг становится активным.
  • inactive – шаг перестаёт быть активным.
  • error – ловит ошибки, возникшие внутри логики туров.

Каждое событие передаёт объект с контекстной информацией, что позволяет детально отслеживать действия пользователя и состояние тура.

tour.on('cancel', () => {
  console.warn('Пользователь отменил тур');
});

tour.on('error', (error) => {
  console.error('Произошла ошибка в туре:', error);
});

Логирование действий пользователя на шаге

Для каждого шага можно регистрировать события, связанные с действиями пользователя, такими как нажатие кнопок, закрытие подсказок или перемещение между шагами.

tour.addStep({
  id: 'step-1',
  text: 'Это первый шаг',
  buttons: [
    {
      text: 'Далее',
      action: tour.next
    }
  ],
  when: {
    show: () => console.log('Показан первый шаг'),
    hide: () => console.log('Скрыт первый шаг')
  }
});

Ключевое отличие when от глобальных событий туров заключается в локализации обработчиков конкретно для данного шага. Это позволяет вести более детальный лог по каждому элементу интерфейса.

Интеграция с внешними системами аналитики

События Shepherd.js легко интегрируются с системами аналитики, такими как Google Analytics или внутренние трекеры. Для этого достаточно вызывать соответствующие функции внутри обработчиков событий:

tour.on('show', (event) => {
  analytics.track('shepherd_step_shown', {
    stepId: event.step.id,
    stepTitle: event.step.options.title || ''
  });
});

tour.on('complete', () => {
  analytics.track('shepherd_tour_completed', { tourId: tour.options.id });
});

Уровни логирования и фильтрация

Для крупных приложений рекомендуется реализовать многоуровневое логирование:

  • info – общая информация о ходе тура.
  • warn – события, которые могут указывать на потенциальные проблемы.
  • error – критические ошибки, влияющие на работу тура.

Применение фильтров по уровням позволяет контролировать объём логов и сосредоточиться на критичных событиях без перегрузки консоли или системы аналитики.

function logEvent(level, message, data = {}) {
  if (level === 'error') console.error(message, data);
  else if (level === 'warn') console.warn(message, data);
  else console.log(message, data);
}

tour.on('error', (err) => logEvent('error', 'Ошибка в туре', err));
tour.on('show', (event) => logEvent('info', 'Показан шаг', { stepId: event.step.id }));

Динамическое логирование шагов

В сложных интерфейсах количество шагов может меняться в зависимости от действий пользователя. Shepherd.js поддерживает динамическое создание и логирование шагов, что позволяет фиксировать события даже для шагов, созданных на лету:

const dynamicStep = tour.addStep({
  id: `step-${Date.now()}`,
  text: 'Динамический шаг',
  when: {
    show: (event) => console.log(`Показан динамический шаг: ${event.step.id}`)
  }
});
tour.show(dynamicStep.id);

Использование глобальных слушателей и управление ими

Shepherd.js предоставляет методы off и once, которые позволяют контролировать жизненный цикл логирования:

  • once – подписка на событие с однократным срабатыванием.
  • off – удаление обработчика для предотвращения утечек памяти или избыточного логирования.
function onTourStart() {
  console.log('Тур начат один раз');
}

tour.once('start', onTourStart);

// Удаление обработчика
tour.off('show', someHandlerFunction);

Такой подход помогает управлять ресурсами и сохраняет читаемость логов при множественных турах или пересоздаваемых шагах.

Практические рекомендации

  • Использовать глобальные события для общих действий и локальные when для шагов с уникальными действиями.
  • Вести лог в структурированном виде для последующего анализа (например, JSON-объекты с полями stepId, event, timestamp).
  • Комбинировать уровни логирования (info, warn, error) для разграничения критичных и вспомогательных событий.
  • Интегрировать Shepherd.js с аналитикой сайта или приложений для отслеживания взаимодействия пользователей и улучшения UX.

Логирование в Shepherd.js обеспечивает гибкую систему контроля над поведением туров и предоставляет мощный инструмент для отладки, анализа и адаптации пользовательских интерфейсов.

Оглавление