# Lead Capture Integration Guide


**Last Updated:** 2026-03-20

## Overview

This guide provides step-by-step instructions for adding the lead capture popup to a new page. The popup is designed to work automatically with minimal configuration, but understanding the integration points helps ensure proper functionality.

## Quick Start

### Basic Integration (Standard Pages)

Add these two lines before the closing `</body>` tag:

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

**That's it!** The popup will automatically:
- Detect page type and show appropriate copy
- Trigger based on page priority (time, scroll, exit-intent) **except on `/tools` hub and calculator URLs** — those are [manual-only](TRIGGER_CONFIGURATION.md#page-exclusions) (footer **Rückruf** / CTAs).
- Handle form submissions
- Sync to HubSpot and Google Sheets

### Example: Adding to a New Product Page

```php
<!-- Your page content here -->

<!-- Footer -->
<?php
$color_fill = '#fff';
$color_background = '#fbfbfb';
$rotate = '0';
$margin_bottom = 'mb-24';
include '../base/footer.php';
?>

<!-- Lead Capture Popup -->
<?php include '../components/lead-capture-popup.php'; ?>

<!-- Lead Capture Triggers -->
<script src="/v2/js/lead-capture-triggers.js"></script>

</body>
</html>
```

## Step-by-Step Integration

### Step 1: Determine Page Type

The popup automatically detects page type based on URL patterns. Common types:

- **Product Pages:** `/schichtplan`, `/zeiterfassung`, `/payroll`
- **Comparison Pages:** `/alternativen/`, `compare_*.php`
- **Tools Pages:** `/tools/`, `tools_*.php`
- **Industry Pages:** `/branchen/`, `industry_*.php`
- **Blog Posts:** `/insights/`, `/ratgeber/`, `/lexikon/`
- **Pricing Pages:** `/preise` (`static_pricing_new.php`), `/pricing` if routed, legacy `static_pricing.php` only if still referenced in triggers

### Step 2: Add Popup Component

Add the include statement before closing `</body>`:

```php
<?php include '../components/lead-capture-popup.php'; ?>
```

**Path Notes:**
- From `v2/pages/`: Use `../components/lead-capture-popup.php`
- From `v2/start.php`: Use `./components/lead-capture-popup.php`
- From root: Use `v2/components/lead-capture-popup.php`

### Step 3: Add Trigger Script

Add the trigger script after the popup component:

```php
<script src="/v2/js/lead-capture-triggers.js"></script>
```

**Optional:** Add cache busting for development:

```php
<script src="/v2/js/lead-capture-triggers.js?v=<?php echo filemtime(__DIR__ . '/js/lead-capture-triggers.js'); ?>"></script>
```

### Step 4: Verify Copy Detection

The popup automatically detects copy based on URL patterns. To verify:

1. Visit the page
2. Open browser console
3. Check if popup shows appropriate headline/description

If copy doesn't match, see [Copy Management Guide](./COPY_MANAGEMENT.md) to add custom copy.

### Step 5: Test Triggers

Test that triggers work correctly:

1. **Time Trigger:** Wait 30-60 seconds (varies by page priority)
2. **Scroll Trigger:** Scroll down 25-40% of page
3. **Exit Intent:** Move mouse to top of browser (desktop) or scroll up rapidly (mobile)

**Tools pages (`/tools`, `/tools/`, `/tools/…`):** Expect **no** automatic time, scroll, or exit-intent popup. Clear session storage if needed, wait well over 60s, scroll deep — still no auto popup. **Do** verify the **manual** path: footer **Rückruf anfordern** (or `window.leadCapturePopup.show('manual-callback')`) opens the popup with the correct tools copy.

## Advanced Integration

### Manual Triggers

Add manual trigger buttons for specific CTAs:

```html
<button onclick="if(window.leadCapturePopup) { window.leadCapturePopup.show('manual-callback'); } else { console.log('Lead capture popup not loaded yet'); }">
    Rückruf anfordern
</button>
```

**Trigger Types:**
- `'manual-callback'`: Bypasses submission restrictions (allows resubmission)
- `'manual'`: Standard manual trigger (respects submission restrictions)

### Custom Trigger Configuration

For pages that need custom trigger behavior, modify `lead-capture-triggers.js` after initialization:

```javascript
// After page load
if (window.leadCaptureTriggers) {
    // Remove default time trigger
    window.leadCaptureTriggers.triggers.delete('time');
    
    // Add custom time trigger
    window.leadCaptureTriggers.addTrigger('time', {
        condition: () => {
            return !window.leadCaptureTriggers.hasShown;
        },
        delay: 45000, // 45 seconds
        once: true
    });
}
```

### Page-Specific Copy

If automatic copy detection doesn't work, add custom copy pattern:

1. Edit `v2/data/lead_capture_copy.php`
2. Add new pattern to `patterns` array:

```php
'my_custom_page' => [
    'urls' => ['/my-custom-page', 'my_custom_page.php'],
    'headline' => 'Custom Headline',
    'description' => 'Custom description text.',
    'funnel_stage' => 'TOF' // or 'MOF' or 'BOF'
],
```

3. Optionally add to quick lookup table in `lead-capture-copy-detector.php`:

```php
'/my-custom-page' => 'my_custom_page',
```

## Integration Checklist

Before deploying, verify:

- [ ] Popup component included (`<?php include '../components/lead-capture-popup.php'; ?>`)
- [ ] Trigger script included (`<script src="/v2/js/lead-capture-triggers.js"></script>`)
- [ ] Copy detection works (check headline/description)
- [ ] Triggers work (time, scroll, exit-intent)
- [ ] Form submission works (Step 1 → Step 2 → Success)
- [ ] HubSpot sync verified (check HubSpot contacts)
- [ ] Google Sheets sync verified (check spreadsheet)
- [ ] Mobile responsiveness tested
- [ ] Accessibility tested (keyboard navigation, screen reader)

## Common Integration Patterns

### Comparison Pages

```php
<!-- Comparison page content -->

<!-- Lead Capture Popup -->
<?php include '../components/lead-capture-popup.php'; ?>

<!-- Lead Capture Triggers -->
<script src="/v2/js/lead-capture-triggers.js"></script>
```

**Note:** Comparison pages use 25% scroll threshold (lower than standard 40%).

### Tools Pages

```php
<!-- Tools page content -->

<!-- Lead Capture Popup -->
<?php include '../components/lead-capture-popup.php'; ?>

<!-- Lead Capture Triggers -->
<script src="/v2/js/lead-capture-triggers.js"></script>
```

**Note:** Tools pages use 60s time delay (longer than standard 30s).

### Blog Posts

```php
<!-- Blog post content -->

<!-- Lead Capture Popup -->
<?php include '../components/lead-capture-popup.php'; ?>

<!-- Lead Capture Triggers -->
<script src="/v2/js/lead-capture-triggers.js"></script>
```

**Note:** Blog posts use optimized triggers (30s delay, 35% scroll, gentler exit intent).

### ShiftOps Report (Gated Content)

```php
<!-- ShiftOps report content -->

<!-- Lead Capture Popup -->
<?php include '../components/lead-capture-popup.php'; ?>

<!-- Lead Capture Triggers -->
<script src="/v2/js/lead-capture-triggers.js"></script>

<script>
// Custom trigger configuration for gated content
if (window.leadCaptureTriggers) {
    // Triggers only enabled after unlock
    window.leadCaptureTriggers.enableAfterUnlock();
}
</script>
```

## Troubleshooting

### Popup Doesn't Appear

1. **Check console:** Look for JavaScript errors
2. **Verify includes:** Ensure both component and script are included
3. **Check session:** Clear `sessionStorage` and `localStorage` if form was previously submitted
4. **Verify triggers:** Check if triggers are firing (add console.log to trigger function)

### Copy Doesn't Match Page

1. **Check URL pattern:** Verify page URL matches pattern in `lead_capture_copy.php`
2. **Add custom pattern:** See [Copy Management Guide](./COPY_MANAGEMENT.md)
3. **Check quick lookup:** Add to quick lookup table for faster detection

### Form Submission Fails

1. **Check API endpoint:** Verify `/v2/api/lead-capture.php` is accessible
2. **Check network tab:** Look for failed requests
3. **Check logs:** Review `v2/logs/lead-capture.log` and `v2/logs/lead-capture-debug.log`
4. **Verify HubSpot:** Check HubSpot API token and form GUID

### HubSpot Sync Issues

1. **Check API token:** Verify `HUBSPOT_API_TOKEN_LEAD_CAPTURE` is set
2. **Check form GUID:** Verify `ORDIO_HUBSPOT_LEAD_CAPTURE_FORM_GUID` matches HubSpot form
3. **Check logs:** Review error logs for HubSpot API errors
4. **Test connectivity:** Visit `/v2/api/lead-capture.php?debug_hubspot=test`

### Google Sheets Sync Issues

1. **Check credentials:** Verify `v2/config/google-sheets-credentials.json` exists or embedded credentials are valid
2. **Check spreadsheet ID:** Verify spreadsheet ID matches in code
3. **Check permissions:** Ensure service account has edit access to spreadsheet
4. **Check logs:** Review error logs for Google Sheets API errors

## Best Practices

1. **Always include both:** Component and trigger script are required
2. **Test thoroughly:** Test on multiple page types before deploying
3. **Monitor logs:** Check logs regularly for errors
4. **Update copy:** Keep copy fresh and relevant to page type
5. **Respect user experience:** Don't override trigger behavior unnecessarily
6. **Mobile first:** Test on mobile devices (triggers behave differently)

## Related Documentation

- [Architecture Overview](./ARCHITECTURE.md) - System architecture and data flow
- [Trigger Configuration](./TRIGGER_CONFIGURATION.md) - Customizing trigger behavior
- [Copy Management](./COPY_MANAGEMENT.md) - Adding/updating copy patterns
- [Troubleshooting Guide](./TROUBLESHOOTING.md) - Common issues and solutions
- [Testing Checklist](./TESTING_CHECKLIST.md) - Pre-deployment testing steps