popup Event

Definition

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

Triggers and Dispatch Conditions of the popup Event

Cases when the popup event should be fired:

• A DOM mutation occurs and the element or any of its nested elements contains one of the following attributes: data-pulse-component, pulse-component, data-pulse-component-type, pulse-component-type, or an identifier with or without the data prefix.

Cases when the popup event should not be fired:

• A DOM mutation occurs and the element or any of its nested elements do not contain one of the following attributes: data-pulse-component, pulse-component, data-pulse-component-type, pulse-component-type, or an identifier with or without the data prefix.

Popup event with type open will not fire if:

• Corresponding attributes were not set on the popup DOM element
• Popup element offsetParent value is null
• Popup element computed style display is none or undefined
• Popup element computed style visibility is hidden

More about popup attributes convention you can read here.

The popup event integration examples

To track component openings automatically by the SDK, we will watch DOM changes and detect new elements injected into the DOM with the pulse-component attribute. The value of this attribute will determine the component name. In addition, a pulse-component-type attribute must be defined to be included in the event parameters.

<modal pulse-component="offer" pulse-component-type="popup">
  ...
</modal>

Dynamic Attributes Support

Popup events support dynamic attributes collection. You can add data-pulse-dynamic-{key} or pulse-dynamic-{key} attributes to popup components to pass contextual information:

<!-- Standard HTML -->
<modal
  pulse-component="offer"
  pulse-component-type="popup"
  pulse-dynamic-offer_id="offer_123"
  pulse-dynamic-discount_percent="20"
  pulse-dynamic-campaign_id="summer_sale"
>
  <div class="offer-content">
    <h2>Special Offer!</h2>
    <p>Get 20% off your next purchase</p>
  </div>
</modal>

<!-- React/Framework compatible -->
<modal
  pulse-component="offer"
  pulse-component-type="popup"
  data-pulse-dynamic-offer_id="offer_123"
  data-pulse-dynamic-discount_percent="20"
  data-pulse-dynamic-campaign_id="summer_sale"
>
  <div class="offer-content">
    <h2>Special Offer!</h2>
    <p>Get 20% off your next purchase</p>
  </div>
</modal>

Dynamic attributes will be collected and included in the additional_properties field of the popup event. The SDK collects dynamic attributes from popup components that have both pulse-component and pulse-component-type attributes defined.

What Data Does a Popup Event Contain?

When a popup component appears or disappears on your website, our analytics script automatically detects this change and collects detailed information about the popup and its context. This information is organized in a structured format called a "schema."

The Popup Event Data Structure

{
    "data": {
      "component": string,
      "component_type": string,
      "click_source": {
        "element": {
          "class_list": string[],
          "id"?: string,
          "name"?: string,
          "node_type": string,
          "value": string
        },
        "group"?: string,
        "section"?: string,
        "popup_component"?: string,
        "popup_component_type"?: string,
        "additional_properties"?: {
          [key: string]: string
        }
      },
      "popup_source": {
        "section": string,
        "group": string
      },
      "additional_properties"?: {
        [key: string]: string
      },
      "action": 'open' | 'close'
    },
    "event": "popup",
    "pulse": "event"
}

Understanding What Each Property Means

What are DOM Elements and Attributes?

DOM Elements are the building blocks of web pages - like buttons, links, images, text boxes, and popup components that users can see and interact with. Think of them as the "things" on a webpage. (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 popup might have:

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

Popup Component Properties

component

The name of the popup component that appeared or disappeared. This is always included with every popup event.

How it's detected: The pulse system reads the value from the pulse-component attribute on the popup element. This name helps you identify which specific popup was shown (like "offer", "newsletter-signup", or "help-tooltip").

component_type

The type or category of the popup component. This is always included with every popup event.

How it's detected: The pulse system reads the value from the pulse-component-type attribute on the popup element. This should typically be set to "popup" to indicate it's a popup component.

action

Whether the popup was opened or closed. This tells you what happened to the popup.

Possible values:

• "open": The popup appeared on the screen (was added to the DOM)
• "close": The popup disappeared from the screen (was removed from the DOM)

click_source Properties

The click_source tells us about the element that triggered the popup to appear, and where it's located on your website. This helps you understand what user action caused the popup to show.

element

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

• 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 (optional): 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 triggering element, including any text from child elements. This helps you understand what the user actually saw and clicked on to trigger the popup (like button text, link text, or other visible content)

section (optional)

The specific area or section of your website where the popup-triggering element is located. This helps you understand which part of your site the user was interacting with when the popup appeared.

How it's detected: The pulse system automatically searches up the DOM tree from the triggering 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 website into larger groups.

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 triggering element was inside another popup, this tells you the name of that parent 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 triggering element 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.

popupsource Properties (optional)_

The popup_source tells us about the website context where the popup itself is located. This is different from click_source - it describes where the popup appears rather than what triggered it.

section

The specific area or section of your website where the popup is displayed.

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

group

A broader category that contains the popup's section.

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 popup's group name.

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 popup or the action that triggered it.

When is this used?

• When you add dynamic attributes (like pulse-dynamic-offer_id="offer_123" or data-pulse-dynamic-campaign_id="summer_sale") to your popup elements or triggering elements
• When you need to track specific context about the popup (like which offer was shown, what discount was applied, or which user segment saw the popup)

What does it contain?

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

Example: If a special offer popup appears, you might track:

"additional_properties": {
    "offer_id": "offer_123",
    "discount_percent": "20",
    "campaign_id": "summer_sale",
    "user_segment": "returning_customer"
}

This extra information helps you answer questions like "Which offers are most effective?" or "What user segments respond best to popups?"