Triggers

Trigger System

Hood Web SDK uses an advanced trigger system that enables precise control over when modals, tags, and other actions are executed.

Trigger Object Structure

Triggers are defined as objects with specific fields that determine when and how actions should be executed. Each trigger object contains:

Basic Trigger Fields

Field	Type	Required	Description
`type`	`string`	Yes	Defines which trigger mechanism to use (scroll, click, timer, etc.). This determines how the SDK will monitor for the triggering condition.
`config`	`object`	No	Contains trigger-specific parameters that customize behavior. Only required for triggers that need configuration (scroll depth, element selectors, timeouts, etc.).

Trigger Definition

{
  "triggers": [
    {
      "type": "scroll",
      "config": {
        "vertical": 75,
        "v_unit": "%"
      }
    },
    {
      "type": "pageView"
    }
  ]
}

Configuration Object Structure

Each trigger type has its own configuration object with specific fields:

{
  "type": "visibility",
  "config": {
    "s": ".my-element",
    "dur": 2000,
    "fire": 1,
    "dom": true
  }
}

Trigger Types Reference

Trigger Type	Configuration Required	Description
`DOMContentLoaded`	No	📄 Fires when DOM structure is ready, before all resources finish loading. Enables fast DOM manipulation and quick user interactions without waiting for assets.
`load`	No	📄 Waits for all resources (images, CSS, JS) to fully load before firing. Ideal for complex modals that need complete page state or heavy content delivery.
`pageView`	No	📄 Fires only on SPA navigation changes (history API events). Does NOT fire on initial page load - use `load` or `DOMContentLoaded` for that. Perfect for tracking virtual page views in single-page applications.
`click`	No	🖱️ Captures any click event on the page and extracts text content. Enables user interaction analytics and click-based personalization.
`beforeunload`	No	👤 Exit intent trigger that fires when user attempts to leave the page (browser close, tab close, navigation away). Perfect for retention campaigns and last-chance offers.
`userConsent`	No	👤 Fires when user consent is granted or changed. Essential for GDPR compliance, cookie banners, and privacy-related user flows.
`scroll`	Yes	🖱️ Monitors user scroll behavior and fires at specified depths. Enables engagement-based targeting, progressive content reveals, and scroll-based analytics.
`visibility`	Yes	🖱️ Tracks when specific elements enter the viewport. Perfect for element-based engagement tracking, lazy loading triggers, and viewport-based analytics.
`formSubmit`	No	🖱️ Captures any form submission event on the page. Enables conversion tracking, thank you messages, and lead generation workflows.
`timer`	Yes	⏰ Fires after a specified delay. Enables delayed popups, progressive engagement, and time-based user experience flows.
`event`	Yes	🔧 Listens for custom JavaScript events you emit. Enables complex user flows, third-party integrations, and custom interaction tracking.

How Matching Works

When an event occurs, the SDK checks all registered tags/modals:

Event type/ID must match the trigger
If matched, filters (if provided) are evaluated
If filters pass, action executes (e.g., show modal, mutate DOM)

Configuration Example

{
  "triggers": [
    { "type": "pageView" },
    { "type": "scroll", "config": { "vertical": 50, "v_unit": "%" } }
  ],
  "filters": [
    { "c": "{{data.user_segment}}", "o": "eq", "m": "prospect" }
  ]
}

This example fires on first pageView or after user scrolls 50% vertically, then shows the action only for prospect users.

Detailed Trigger Type Descriptions

The following sections provide comprehensive details for each trigger type, including configuration options, usage examples, and practical applications. Each trigger is organized by category for easy navigation.

📄 Page Load Triggers

These triggers fire at different stages of page loading, from DOM parsing to full resource loading. Choose the appropriate trigger based on when you need your action to execute.

DOMContentLoaded

📄 Page Load

Purpose: 📄 Fires as soon as DOM structure is loaded, before all resources are loaded.

Configuration: None required

Usage:

{
  "type": "DOMContentLoaded"
}

When to use:

Quick actions that don’t wait for resources
DOM manipulation before full page load
Fast user interactions

load

📄 Page Load

Purpose: 📄 Fires only when all page resources (images, CSS, JS) are fully loaded.

Configuration: None required

Usage:

{
  "type": "load"
}

When to use:

Complex modals requiring all resources
Actions that should execute only when page is fully ready
Heavy content delivery

pageView

📄 Page Load

Purpose: 📄 Fires only on SPA navigation changes (history API events like pushState, replaceState, popstate). Does NOT fire on initial page load.

Configuration: None required

Usage:

{
  "type": "pageView"
}

When to use:

SPA navigation tracking
Virtual page view analytics
Route change monitoring
Internal navigation events

Important: This trigger only fires when there are internal navigation changes in SPA applications. For initial page load tracking, use load or DOMContentLoaded triggers instead.

👤 User Behavior Triggers

These triggers monitor user behavior patterns, including consent management and exit intent detection. They help you respond to user actions and preferences.

👤 User Behavior

Purpose: 👤 Fires when user consent is granted or changed.

Configuration: None required

Usage:

{
  "type": "userConsent"
}

When to use:

GDPR compliance
Cookie banners
Privacy messages
Consent-based analytics

beforeunload

👤 User Behavior

Purpose: 👤 Exit intent trigger that fires when user attempts to leave the page (browser close, tab close, navigation away, or back button).

Configuration: None required

Usage:

{
  "type": "beforeunload"
}

When to use:

Retention campaigns
Last-chance offers
Newsletter signup
Exit intent popups
Cart abandonment recovery

Important: This is an exit intent trigger that detects when users are about to leave your page. It fires on browser close, tab close, navigation to other sites, or back button clicks.

🖱️ Interaction Triggers

These triggers respond to user interactions with your page, including clicks, scrolling, form submissions, and element visibility. They enable engagement-based targeting and user behavior analytics.

click

🖱️ Interaction

Purpose: 🖱️ Captures any click event on the page and extracts text content.

Configuration: None required

Usage:

{
  "type": "click"
}

When to use:

User interaction analytics
Click-based personalization
General user behavior tracking

scroll

🖱️ Interaction

Purpose: 🖱️ Fires when user scrolls to a certain depth of the page.

Configuration Object:

{
  "type": "scroll",
  "config": {
    "vertical": 75,
    "horizontal": 50,
    "v_unit": "%",
    "h_unit": "px"
  }
}

Configuration Fields:

Field	Type	Description	Default	Values	Example
`vertical`	`number`	Threshold for vertical scroll. Can be percentage (0-100) or pixels depending on `v_unit`. Controls when vertical scroll trigger fires.	`0`	-	`75`
`horizontal`	`number`	Threshold for horizontal scroll. Can be percentage (0-100) or pixels depending on `h_unit`. Controls when horizontal scroll trigger fires.	`0`	-	`50`
`v_unit`	`string`	Unit for vertical scroll measurement.	`"px"`	`"px"`, `"%"`	`"px"`
`h_unit`	`string`	Unit for horizontal scroll measurement.	`"px"`	`"px"`, `"%"`	`"px"`

When to use:

Engagement tracking
Displaying content when user shows interest
A/B testing based on scroll behavior

visibility

🖱️ Interaction

Purpose: 🖱️ Fires when a specific element becomes visible on screen.

Configuration Object:

{
  "type": "visibility",
  "config": {
    "s": ".my-element",
    "dur": 2000,
    "fire": 1,
    "dom": true
  }
}

Configuration Fields:

Field	Type	Description	Default	Values	Example
`s`	`string`	CSS selector targeting specific elements to monitor. Supports any valid CSS selector (classes, IDs, attributes). Enables precise element-based triggers.	-	-	`".my-element"`
`dur`	`number`	Duration in milliseconds the element must be visible before firing. Prevents accidental triggers from quick scrolls and ensures genuine user engagement.	`0`	-	`2000`
`fire`	`number`	Trigger behavior: 1 = per page, 2 = per element, 3 = always. Controls trigger frequency to prevent spam and optimize performance.	`1`	`1`, `2`, `3`	`1`
`dom`	`boolean`	Wait for DOM changes if element will show at later time. Enables dynamic DOM monitoring for dynamically added content. Essential for SPA applications and AJAX-loaded content.	`false`	`true`, `false`	`true`

Fire Options:

1: Once per page (default)
2: Once per element
3: Every time element becomes visible

When to use:

Element-based engagement tracking
Dynamic content visibility
SPA applications with changing DOM

formSubmit

🖱️ Interaction

Purpose: 🖱️ Fires when user submits any form on the page.

Configuration: None required

Usage:

{
  "type": "formSubmit"
}

When to use:

Thank you messages
Lead generation
Conversion tracking

⏰ Time-based Triggers

These triggers execute actions based on time delays and custom events. They enable delayed interactions, progressive engagement, and custom event handling.

timer

⏰ Time-based

Purpose: ⏰ Fires after a specified time delay.

Configuration Object:

{
  "type": "timer",
  "config": {
    "time": 5000
  }
}

Configuration Fields:

Field	Type	Description	Default	Values	Example
`time`	`number`	Delay in milliseconds before firing.	`0`	-	`5000`

When to use:

Delayed popups
Progressive engagement
Time-based user experience flows

🔧 Custom Triggers

These triggers enable custom event handling and third-party integrations. They allow you to create sophisticated user flows and respond to custom JavaScript events.

event

🔧 Custom

Purpose: 🔧 Fires when a custom event occurs.

Configuration Object:

{
  "type": "event",
  "config": {
    "name": "myCustomEvent",
    "target": "document"
  }
}

Configuration Fields:

Field	Type	Description	Default	Values	Example
`name`	`string`	Name of the custom event to listen for.	-	-	`"myCustomEvent"`
`target`	`string`	DOM element to attach the event listener to.	`"document"`	`"document"`, `"window"`, CSS selector	`"document"`

How to emit custom event:

// Emit custom event
window.dispatchEvent(new CustomEvent('myCustomEvent', {
  detail: { someData: 'value' }
}));

When to use:

Custom user flows
Third-party integrations
Complex interaction tracking

⚙️ Advanced Options

These advanced configuration options provide additional control over trigger behavior and execution logic.

require_all_triggers

⚙️ Advanced

Purpose: ⚙️ Requires all defined triggers to be met before action fires.

Configuration:

{
  "require_all_triggers": true
}

When to use:

Complex targeting logic
Combining multiple conditions

Advanced personalization

LinkedIn Facebook Instagram