click Event

Definition

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

Triggers and Dispatch Conditions of the click Event

Cases when the click event should be fired:

• Click happens on the <button> or <a>(button or anchor) element
• Click happens on a clickable element

Cases when the click event should not be fired:

• Click happens on a non-trackable element or on an element marked by pulse-dnt attribute(non trackable)

The click event integration examples

Section, section group usage example:

After the user clicks on a link or a button, the tracking SDK iterates through the DOM elements from bottom to top, starting from the clicked element to find the section and section groups. The first element with a pulse-section attribute will be considered as a current section for the clicked element. The SDK will continue the search to find an element with the pulse-section-group attribute, which will be our section group. If there were no parent section groups, the SDK would pick the section name as a name for the section group and vice-versa. If the SDK fails to find the section and section groups, it will return null as the section name. The result of this search is a pair of section and section group names.

<div pulse-section-group="templates">
  <div pulse-section="templates-instagram-story">...</div>
  <div pulse-section="templates-instagram-square">...</div>
  <div pulse-section="templates-facebook-cover">
    <button>Click on Me!</button>
  </div>
</div>

Non Button or Links usage example:

The SDK, by default, will only track the clicks on button and anchor tags. If the clickable element is not a button or a link, the developer can mark it as clickable using pulse-clickable.

<div pulse-clickable>Click on Me!</div>

Button Names:

An additional pulse-name attribute can be added to clickable elements to be included in the parameters of the click event. If the pulse-name attribute was not provided, the SDK would fall back to using the name attribute if it's defined.

<button pulse-name="select-template">Click on Me!</button>

Dynamic Attributes:

You can add dynamic data attributes to elements to pass contextual information that will be collected and included in the click event. Use either data-pulse-dynamic-{key} or pulse-dynamic-{key} format where {key} is your custom property name.

React/Framework Compatibility: Use data-pulse-dynamic-{key} format in React and other frameworks that require the data- prefix for custom attributes.

<!-- Standard HTML -->
<button
  pulse-name="upload-button"
  pulse-dynamic-file_id="12345"
  pulse-dynamic-file_type="image"
  pulse-dynamic-user_id="user_789"
>
  Upload File
</button>

<!-- React/Framework compatible -->
<button
  pulse-name="upload-button"
  data-pulse-dynamic-file_id="12345"
  data-pulse-dynamic-file_type="image"
  data-pulse-dynamic-user_id="user_789"
>
  Upload File
</button>

The SDK will automatically collect these attributes and include them in the additional_properties field of the click event:

{
  "additional_properties": {
    "file_id": "12345",
    "file_type": "image",
    "user_id": "user_789"
  }
}

Best Practices:

• Use descriptive, unique property names
• Keep property names in kebab-case (e.g., file_id, user_role)
• Avoid embedding variables in attribute names - use static names with dynamic values
• Dynamic attributes are collected from both the clicked element and any parent popup components

Do not track:

There might be some sections on the website that we don’t want to track their child element clicks, or we do not want to track the section name as a source for the upcoming events. In these scenarios, the developer can add pulse-dnt and pulse-dnt-source attributes to the section, section group, or a clickable element to disable tracking.

Ignore Everything:

Do not track clicks inside this section. Do not fire click events, and do not overwrite the previous source parameter.

<div pulse-section="templates" pulse-dnt>
  ...
</div>

Ignore Source:

Tracks clicks and can fire click events, but clicking on child elements of this section does not overwrite the source.

<div pulse-section="templates" pulse-dnt-source>
  ...
</div>

What Data Does a Click Event Contain?

When someone clicks on a trackable element on your website, our analytics script automatically collects detailed information about what was clicked and where it happened. This information is organized in a structured format called a "schema."

The Click Event Data Structure

{
    'pulse': 'event',
    'event': 'click',
    '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
        }
    }
}

Understanding What Each Property Means

What are DOM Elements and Attributes?

DOM Elements are the building blocks of web pages - like buttons, links, images, and text boxes that users can see and interact with. Think of them as the "things" on a webpage that people can click on. (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 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 was clicked and where it's located on your website. This information is always included with every click event.

element

This describes the specific thing that was clicked (like a button or link):

• class_list: A list of CSS styling categories applied to the element (helps identify what type of 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 element does)
• node_type: What type of element it is (examples: "BUTTON" for buttons, "A" for links, "DIV" for containers) (Learn more)
• value: The text content of the clicked element, including any text from child elements. This helps you understand what the user actually saw and clicked on (like button text, link text, or other visible content)

section (optional)

The specific area or section of your website where the click happened. This helps you understand which part of your site users are interacting with (like "header", "sidebar", "product-gallery").

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. See the section usage examples above for implementation details.

group (optional)

A broader category that contains multiple sections. This helps organize different parts of your website into larger groups (like "navigation", "content", "footer").

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. See the section usage examples above for implementation details.

popupcomponent (optional)_

If the click happened 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 click was in 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. Think of it as a flexible container for any additional data you want to track about the click.

When is this used?

• When you add dynamic attributes (like pulse-dynamic-file_id="12345" or data-pulse-dynamic-user_role="admin") to your HTML elements
• When you need to track specific context about what the user was doing (like which file they were working on, their user role, or which product they were viewing)

What does it contain?

• Custom key-value pairs that provide context about the user's action
• Information that helps you understand not just what was clicked, but why or in what context it was clicked

Example: If someone clicks an "Upload" button while working on a specific project, you might track:

"additional_properties": {
    "project_id": "proj_123",
    "file_type": "image",
    "user_role": "editor"
}

This extra information helps you answer questions like "Which projects are users most active in?" or "What types of files do editors upload most often?"