Documentation Grafana Cloud Monitor applications Frontend Observability Instrument Navigation instrumentation

Track SPA soft navigation

The Faro Web SDK Navigation instrumentation automatically captures soft navigation events in single-page applications (SPAs). Unlike traditional page navigation events that trigger a full browser reload, soft navigation events update content dynamically within the same page, making them critical to monitor for understanding user journeys in modern web applications.

Tracking navigation events helps you to:

• Performance monitoring: Track how long it takes for different routes in your SPA to load and become interactive
• User journey analysis: Understand how users navigate through your application
• Route-specific issues: Identify performance bottlenecks or errors associated with specific navigation paths
• Conversion tracking: Monitor critical user flows and identify where users drop off

Overview

In single-page applications, users navigate between different views or pages without triggering a full page reload.

The Navigation instrumentation detects these soft navigation events by monitoring:

• URL changes (via the History API, the Navigation API, and hash changes)
• User interactions (clicks, keyboard events)
• DOM updates
• HTTP requests and other browser activities during navigation

How it works

The Navigation instrumentation tracks related activities within a time window to determine when a soft navigation occurs:

1. Detection: Monitors user interactions that might trigger a navigation
2. Activity tracking: Captures all related events (URL changes, HTTP requests, DOM updates) that occur during the navigation
3. Completion: After activity settles (no new events for 100ms), the navigation is considered complete and an event is sent

For navigation with long-running HTTP requests, the instrumentation waits for the requests to complete before finalizing the navigation event.

Enable the Navigation instrumentation

The Navigation instrumentation is not enabled by default and requires explicit configuration:

JavaScript Copy

import { initializeFaro } from '@grafana/faro-web-sdk';

initializeFaro({
  url: 'https://my-domain.my-tld/collect/{app-key}',
  app: {
    name: 'my-app',
  },

  experimental: {
    trackNavigation: true,
  },
});

If you’re using custom instrumentation, you can manually add the Navigation instrumentation:

JavaScript Copy

import { NavigationInstrumentation } from '@grafana/faro-web-sdk';

const instrumentations = [
  // ...other instrumentations
  new NavigationInstrumentation(),
];

Use cases

The Navigation instrumentation is particularly valuable for:

• Performance monitoring: Track how long it takes for different routes in your SPA to load and become interactive
• User journey analysis: Understand how users navigate through your application
• Route-specific issues: Identify performance bottlenecks or errors associated with specific navigation paths
• Conversion tracking: Monitor critical user flows and identify where users drop off