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

type (string, required): Defines which trigger mechanism to use (scroll, click, timer, etc.). This determines how the SDK will monitor for the triggering condition.
config (object, optional): 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
  }
}

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

Fires when DOM structure is ready, before all resources finish loading. Enables fast DOM manipulation and quick user interactions without waiting for assets.

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

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.

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

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.

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.

Fires when user consent is granted or changed. Essential for GDPR compliance, cookie banners, and privacy-related user flows.

Configuration: None required

Usage:

{
  "type": "userConsent"
}

When to use:

GDPR compliance
Cookie banners
Privacy messages
Consent-based analytics

beforeunload

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.

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

Captures any click event on the page and extracts text content. Enables user interaction analytics and click-based personalization.

Configuration: None required

Usage:

{
  "type": "click"
}

When to use:

User interaction analytics
Click-based personalization
General user behavior tracking

scroll

Monitors user scroll behavior and fires at specified depths. Enables engagement-based targeting, progressive content reveals, and scroll-based analytics.

Configuration Object:

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

Configuration Fields:

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

When to use:

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

visibility

Tracks when specific elements enter the viewport. Perfect for element-based engagement tracking, lazy loading triggers, and viewport-based analytics.

Configuration Object:

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

Configuration Fields:

s (string, required): CSS selector targeting specific elements to monitor. Supports any valid CSS selector (classes, IDs, attributes). Enables precise element-based triggers. Example: ".my-element"
dur (number, default: 0): Duration in milliseconds the element must be visible before firing. Prevents accidental triggers from quick scrolls and ensures genuine user engagement. Example: 2000
fire (number, default: 1): Trigger behavior: 1 = per page, 2 = per element, 3 = always. Controls trigger frequency to prevent spam and optimize performance. Values: 1, 2, 3. Example: 1
dom (boolean, default: false): 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. Example: 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

Captures any form submission event on the page. Enables conversion tracking, thank you messages, and lead generation workflows.

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

Fires after a specified delay. Enables delayed popups, progressive engagement, and time-based user experience flows.

Configuration Object:

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

Configuration Fields:

time (number, default: 0): Delay in milliseconds before firing. Example: 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

Listens for custom JavaScript events you emit. Enables complex user flows, third-party integrations, and custom interaction tracking.

Configuration Object:

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

Configuration Fields:

name (string, required): Name of the custom event to listen for. Example: "myCustomEvent"
target (string, default: "document"): DOM element to attach the event listener to. Values: "document", "window", CSS selector. Example: "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

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