Skip to main content

navigation Event

Definition​

This document provides a detailed walkthrough of the firing navigation built-in event

Triggers and Dispatch Conditions of the navigation Event​

Cases when the navigation event should be fired:

  • The SDK starts on a page (initial: true)
  • The URL changes without a page load, through history.pushState, history.replaceState, a hash change, or the browser's Back and Forward buttons (initial: false)
  • The session is renewed, with source: "session_reset", or tracking consent is given, with source: "consent_change". These events report the current page again.

Cases when the navigation event should not be fired:

  • The URL is the same as the URL of the previous navigation event of the page. This also applies to a session_reset or consent_change navigation on a page whose URL hasn't changed.

What Data Does a Navigation Event Contain?​

{
    'pulse': 'event',
    'event': 'navigation',
    'data': {
        'initial': boolean,
        'source'?: 'session_reset' | 'consent_change',
        'click_source': {
            'element'?: {
                'class_list': string[],
                'id'?: string,
                'name'?: string,
                'type': string,
                'value': string
            },
            'section'?: string,
            'group'?: string,
            'popup_component'?: string,
            'popup_component_type'?: string,
            'tab_id'?: string,
            'url'?: string,
            'type'?: 'click' | 'contextmenu',
            'additional_properties'?: {
                [key: string]: string
            },
            'navigate_label'?: string
        }
    }
}

click_source is an empty object ({}) when no click caused the navigation, or when the SDK can't tell which one did.

Where click_source Comes From​

The SDK fills click_source with the click that caused the navigation, found in one of these ways:

  • A declared click. A click on an element with the pulse-navigate attribute is the source of the next navigation within 30 seconds in the same tab, or of the new tab it opens (within 6 seconds for a tab the browser opens), and adds navigate_label. See Declared Navigation Source.
  • A recent click in the same tab. Otherwise, for a navigation inside the page, the SDK takes a click made in the same tab about 500 ms before it; for a full page load, about 3.5 seconds before it.
  • A recent click in another tab. Otherwise, for the first page of a new tab, the SDK takes the click, in another tab, that opened it, about 6 seconds before it.

For the first page of a new tab, click_source.type is set too: click, or contextmenu when the tab was opened from a link's context menu.

Understanding What Each Property Means​

initial​

true for the navigation event sent when the SDK starts on a page, false for the following ones.

source (optional)​

Set when the event re-reports the current page: session_reset after the session was renewed, consent_change after tracking consent was given.

click_source​

element, section, group, popup_component, popup_component_type, additional_properties​

The clicked element and where it is on the page, with the same meaning as in the click event. element.type is the element's tag name, for example BUTTON or A.

tabid (optional)_​

The id of the tab the click happened in. For a new tab, it is the id of the tab that opened it, also sent as opener_tab_id on every event of the new tab.

url (optional)​

The URL of the page the click happened on.

type (optional)​

How a new tab was opened from its opener: click (a middle-click counts as a click) or contextmenu. Not set for a navigation in the same tab.

navigatelabel (optional)_​

The value of the pulse-navigate (or data-pulse-navigate) attribute of the declared click that caused this navigation. Not set when the click wasn't declared, or when the attribute has no value. See Declared Navigation Source.