navigation Event

Definition

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

Triggers and Dispatch Conditions of the navigation Event

Cases when the navigation event should be fired:

• If the route streams a new value

note

The URL will compose based on provided values

What Data Does a Navigation Event Contain?

When users navigate between different screens or routes in your miniapp, our analytics script automatically collects detailed information about the navigation action and what triggered it. This information is organized in a structured format called a "schema."

The Navigation Event Data Structure

{
    'pulse': 'event',
    'event': 'navigation',
    'data': {
        'click_source': {
            'element': {
                'class_list': string[],
                'id'?: string,
                'name': string,
                'node_type': 'A',
                'value': string
            },
            'group'?: string,
            'section'?: string,
            'popup_component'?: string,
            'popup_component_type'?: string,
            'additional_properties'?: {
                [key: string]: string
            }
        },
        'initial': boolean
    }
}

Understanding What Each Property Means

What are DOM Elements and Attributes?

DOM Elements are the building blocks of miniapp interfaces - like buttons, links, navigation tabs, and menu items that users can interact with to move around your app. Think of them as the "things" in your miniapp that people tap to navigate. (Learn more about DOM elements)

DOM Element Attributes are like name tags or labels attached to these elements that provide extra information about them. (Learn more about DOM attributes) For example, a navigation button might have:

• An ID (like a unique identifier)
• A class (like a category it belongs to)
• A name (what we call it internally)

click_source Properties

The click_source tells us exactly what element triggered the navigation and where it's located in your miniapp. This helps you understand how users move through your app.

element

This describes the specific element that was clicked or interacted with to trigger the navigation:

• class_list: A list of CSS styling categories applied to the element (helps identify what type of navigation element it is and how it looks) (Learn more)
• id (optional): An identifier for this specific element. The system first tries to use the element's DOM id attribute. If no DOM id exists, it falls back to the pulse-name attribute value. If neither exists, this property is not included in the event data. (Learn more about DOM id)
• name: The custom name you've given this element using the pulse-name attribute (helps you recognize what this navigation element does)
• node_type: What type of element it is (examples: "BUTTON" for buttons, "A" for links, "DIV" for custom navigation elements) (Learn more)
• value: The text content of the navigation element that was tapped, including any text from child elements. This helps you understand what the user actually saw and interacted with to navigate (like navigation button text, menu item text, or other visible content in your miniapp)

section (optional)

The specific area or section of your miniapp where the navigation was triggered from. This helps you understand which part of your app users are navigating from (like "main-menu", "sidebar", "bottom-nav").

How it's detected: The pulse system automatically searches up the DOM tree from the clicked element to find the first parent element with a data-pulse-section or pulse-section attribute. The value of this attribute becomes the section name.

group (optional)

A broader category that contains multiple sections. This helps organize different parts of your miniapp navigation into larger groups (like "primary-navigation", "secondary-navigation", "footer-links").

How it's detected: The pulse system continues searching up the DOM tree to find an element with a data-pulse-section-group or pulse-section-group attribute. The value of this attribute becomes the group name. If no group is found but a section exists, the section name is used as the group name, and vice versa.

popupcomponent (optional)_

If the navigation was triggered from inside a popup window or modal dialog, this tells you the name of that popup component.

How it's detected: The pulse system searches for a parent element with a pulse-component attribute. The value of this attribute becomes the popup component name.

popupcomponent_type (optional)_

If the navigation was triggered from a popup, this describes what type of popup it was (like "modal", "tooltip", "dropdown").

How it's detected: The pulse system searches for a parent element with a pulse-component-type attribute. The value of this attribute becomes the popup component type.

additionalproperties (optional)_

This is where any extra custom information gets stored about the navigation trigger. Think of it as a flexible container for any additional data you want to track about the navigation action.

When is this used?

• When you add dynamic attributes (like pulse-dynamic-target_screen="profile" or data-pulse-dynamic-user_flow="onboarding") to your navigation elements
• When you need to track specific context about the navigation (like which screen they're going to, what user flow they're in, or their current progress level)

What does it contain?

• Custom key-value pairs that provide context about the navigation action
• Information that helps you understand not just what navigation element was clicked, but why or in what context the navigation happened

Example: If someone taps a "Go to Profile" button, you might track:

"additional_properties": {
    "target_screen": "user_profile",
    "user_flow": "settings_access",
    "current_step": "3_of_5",
    "user_type": "premium_user"
}

initial

This tells you whether this navigation event is the very first one that occurred after your analytics SDK was initialized in the miniapp session.

Possible values:

• true: This is the first navigation event since the SDK started tracking (typically the app's initial load or first screen shown)
• false: This is a subsequent navigation event (user navigating to different screens after the initial load)

Why is this useful?

• Helps distinguish between app startup navigation and user-driven navigation
• Allows you to separate initial app loading analytics from actual user behavior patterns
• Useful for measuring app startup performance and initial user experience