Documentation Grafana Cloud Observe and act 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.

Configure the Navigation instrumentation

The Navigation instrumentation is enabled by default in the Faro Web SDK. No additional configuration is required.

To disable it while using the default instrumentation set, pass trackNavigation: false to getWebInstrumentations():

JavaScript Copy

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

initializeFaro({
  url: 'https://my-domain.my-tld/collect/{app-key}',
  app: {
    name: 'my-app',
  },
  instrumentations: getWebInstrumentations({ trackNavigation: false }),
});

If you provide a custom instrumentations array, the SDK uses it instead of the default instrumentations. Add the Navigation instrumentation manually if you want to keep soft navigation tracking:

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