# Lead Capture Component Documentation

**Last Updated:** 2026-03-24

Complete documentation for the two-step progressive lead capture popup component.

## Overview

The lead capture popup (`v2/components/lead-capture-popup.php`) is a reusable two-step progressive form with Ordio branding, dynamic copy detection, and HubSpot integration.

## File Location

- **Component:** `v2/components/lead-capture-popup.php`
- **Trigger Script:** `v2/js/lead-capture-triggers.js`
- **Copy Detector:** `v2/components/lead-capture-copy-detector.php`
- **API Endpoint:** `v2/api/lead-capture.php`

## Features

### 1. Two-Step Progressive Form

- **Step 1:** Basic information (name, phone) - Required
- **Step 2:** Additional information (email, notes, call preference) - Optional
- Smooth transitions between steps
- Success state with next steps

### 2. Dynamic Copy Detection

- Automatically detects page type
- Adjusts headline and description based on page
- Supports multiple page types (comparison, product, industry, etc.)
- Funnel stage detection

### 3. Trigger System

- Time-based triggers (after X seconds)
- Scroll-based triggers (after X% scroll)
- Exit intent triggers (mouse leaving viewport)
- Blog-optimized triggers (longer delays)
- Session-based suppression (once per session)
- Page-based suppression (once per page)
- **Tools pages (`/tools`…):** No automatic time/scroll/exit-intent scheduling; popup still loads and uses copy detection; opens via manual CTAs (`manual-callback`). See [TRIGGER_CONFIGURATION.md](../lead-capture/TRIGGER_CONFIGURATION.md#page-exclusions).

### 4. HubSpot Integration

- Forms API v3 submission
- CRM API v3 fallback
- Activity tracking via `hubspotutk`
- Pre-submission page view tracking
- Contact identification by `hubspotutk`

## Integration Pattern

### 1. Include Component

```php
<!-- Before closing </body> tag -->
<?php include '../components/lead-capture-popup.php'; ?>
<script src="/v2/js/lead-capture-triggers.min.js?v=<?php echo filemtime(__DIR__ . '/../js/lead-capture-triggers.min.js'); ?>"></script>
```

### 2. Component Initialization

The component automatically initializes via `lead-capture-triggers.js`:

```javascript
// Automatic initialization
class LeadCaptureTriggers {
  constructor() {
    // Sets up triggers based on page type
  }
}
```

## Form Fields

### Step 1 Fields (Required)

- `name` (text) - Full name
- `phone` (tel) - Phone number

### Step 2 Fields (Optional)

- `email` (email) - Email address
- `notes` (textarea) - Additional notes
- `call_preference` (radio) - Call preference:
  - "Sofort (heute noch)"
  - "Morgen"
  - "Diese Woche"

## API Integration

### Endpoint

`/v2/api/lead-capture.php`

### Request Payload (Step 1)

```javascript
{
    name: string,
    phone: string,
    sourcePage: string,        // Auto-detected
    leadSource: string,        // Auto-detected
    triggerType: string,       // Auto-detected
    utm_source: string,
    utm_medium: string,
    utm_campaign: string,
    utm_term: string,
    utm_content: string,
    gclid: string,
    hubspotutk: string
}
```

### Request Payload (Step 2)

```javascript
{
    email: string,             // Optional
    notes: string,             // Optional
    callPreference: string,    // Optional
    leadId: string             // From Step 1 response
}
```

## Trigger Configuration

### Standard Triggers

- **Time Trigger:** 30 seconds after page load
- **Scroll Trigger:** 60% page scroll
- **Exit Intent:** Mouse leaving viewport

### Blog-Optimized Triggers

- **Time Trigger:** 60 seconds after page load
- **Scroll Trigger:** 40% page scroll (lower threshold for longer content)

### Suppression Rules

- **Session Suppression:** Once per session (stored in `sessionStorage`)
- **Page Suppression:** Once per page (stored in `sessionStorage`)
- **Submission Suppression:** 30 days after submission (stored in `localStorage`)

## Copy Detection

The component uses `lead-capture-copy-detector.php` to detect:

- **Page Type:** comparison, product, industry, template, download, webinar, homepage, pricing, static
- **Funnel Stage:** awareness, consideration, decision
- **Headline:** Dynamic based on page type (from `v2/data/lead_capture_copy.php` via `getLeadCaptureCopy()`)
- **Description:** Dynamic based on page type (same source)—**benefit + callback + trust**; avoid repeating speed/timing here when the headline or CTA already signals urgency (see [LEAD_CAPTURE_COPY_BEST_PRACTICES.md](../lead-capture/LEAD_CAPTURE_COPY_BEST_PRACTICES.md)).

### Step 1 primary CTA (global)

The Step 1 submit button label is **hard-coded** in `lead-capture-popup.php` (not per-URL). To change it site-wide, edit the `<span class="button-text">` inside `#step1-submit-btn`. Keep wording aligned with the telephone consent line and [FONIO_CALLBACK_COPY.md](../lead-capture/FONIO_CALLBACK_COPY.md).

## HubSpot Form Configuration

- **Form GUID:** `9f9d4e35-d8d9-4283-93b6-1a789e0a1281`
- **Constant:** `HUBSPOT_FORM_GUID_LEAD_CAPTURE`
- **API Type:** Forms API v3 (with CRM API v3 fallback)

## Usage Examples

### Example 1: Standard Integration

```php
<!-- In page template -->
<?php include '../components/lead-capture-popup.php'; ?>
<script src="/v2/js/lead-capture-triggers.min.js"></script>
```

### Example 2: Custom Trigger

```javascript
// Manually trigger popup
if (window.leadCapturePopup) {
  window.leadCapturePopup.show();
}
```

### Example 3: Disable for Specific Page

```php
<!-- Skip include for specific pages -->
<?php if ($pageType !== 'shiftops-report'): ?>
    <?php include '../components/lead-capture-popup.php'; ?>
<?php endif; ?>
```

## Browser Compatibility

- Modern browsers (Chrome, Firefox, Safari, Edge)
- Requires ES6+ support
- Requires `sessionStorage` and `localStorage` support
- Gracefully handles missing features

## Related Documentation

- [Lead Capture System](../../systems/lead-capture/README.md) - Complete system documentation
- [HubSpot API Reference](../apis/HUBSPOT_API_REFERENCE.md) - API endpoint documentation
- [Form-to-Page Mapping](../forms/FORM_TO_PAGE_MAPPING.md) - Which pages use this component