# Lead Capture Quick Reference


**Last Updated:** 2026-03-28

## Blocking overlays

Automatic triggers pause while other modals are open (demo, template download, tool export, etc.). Registry: `v2/js/ordio-lead-capture-blocking-registry.js` (loaded in `head.php`). Details: [TRIGGER_CONFIGURATION.md § Blocking overlays](./TRIGGER_CONFIGURATION.md#blocking-overlays-automatic-triggers).

## Common Tasks

### Tools pages (`/tools`…)

Automatic time/scroll/exit-intent triggers are **off**; the popup still loads for **manual** opens (`manual-callback`). See [TRIGGER_CONFIGURATION.md](./TRIGGER_CONFIGURATION.md#page-exclusions).

### Add Popup to New Page

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

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

### Add Manual Trigger Button

```html
<button onclick="if(window.leadCapturePopup) { window.leadCapturePopup.show('manual-callback'); }">
    Rückruf anfordern
</button>
```

### Add Custom Copy Pattern

1. Edit `v2/data/lead_capture_copy.php`:
```php
'my_page' => [
    'urls' => ['/my-page', 'my_page.php'],
    'headline' => 'Hast du Fragen?',
    'description' => 'Wir helfen dir gerne weiter.',
    'funnel_stage' => 'TOF'
],
```

2. (Optional) Add to quick lookup in `lead-capture-copy-detector.php`:
```php
'/my-page' => 'my_page',
```

### Customize Triggers

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

## File Locations

| Component | File Path |
|-----------|-----------|
| Popup Component | `v2/components/lead-capture-popup.php` |
| Copy Detector | `v2/components/lead-capture-copy-detector.php` |
| Copy Config | `v2/data/lead_capture_copy.php` |
| API Endpoint | `v2/api/lead-capture.php` |
| Trigger Script | `v2/js/lead-capture-triggers.js` |
| Blocking registry (head) | `v2/js/ordio-lead-capture-blocking-registry.js` |
| Logs | `v2/logs/lead-capture.log`<br>`v2/logs/lead-capture-debug.log` |
| Google Sheets Creds | `v2/config/google-sheets-credentials.json` |

## Key Functions

### Frontend (JavaScript)

```javascript
// Show popup manually
window.leadCapturePopup.show('manual');
window.leadCapturePopup.show('manual-callback'); // Bypasses restrictions

// Check if popup is open
window.leadCapturePopup.isOpen();

// Reset state (for testing)
window.resetLeadCapture();

// Check trigger status
window.leadCaptureTriggers.hasShown;
window.leadCaptureTriggers.getPagePriority();
```

### Backend (PHP)

```php
// Get copy for current page
getLeadCaptureCopy(); // Returns ['headline', 'description', 'type', 'funnel_stage']

// Debug copy detection
debugLeadCaptureCopy(); // Returns debug info

// Performance check
getLeadCapturePerformance(); // Returns timing info
```

## Configuration Constants

### HubSpot

```php
HUBSPOT_API_TOKEN_LEAD_CAPTURE      // API token
ORDIO_HUBSPOT_PORTAL_ID             // Portal ID: 145133546
ORDIO_HUBSPOT_LEAD_CAPTURE_FORM_GUID // Form GUID: 9f9d4e35-d8d9-4283-93b6-1a789e0a1281
```

### Google Sheets

```php
Spreadsheet ID: 1gHzf0CcCACPPLo3Xb4aBcO9cguraVa7eeLyYZvqCBAk
Service Account: ordio-webinar-sheets@ordio-472310.iam.gserviceaccount.com
```

## Debugging Commands

### Browser Console

```javascript
// Check popup status
window.leadCapturePopup?.isOpen();

// Check trigger status
console.log(window.leadCaptureTriggers?.hasShown);
console.log(window.leadCaptureTriggers?.triggers);

// Manually trigger
window.leadCapturePopup?.show('manual');

// Reset state
window.resetLeadCapture();

// Check session storage
console.log({
    shown: sessionStorage.getItem('lead_capture_shown'),
    submitted: sessionStorage.getItem('lead_capture_submitted'),
    expires: localStorage.getItem('lead_capture_submitted_expires')
});
```

### Server Logs

```bash
# Monitor logs
tail -f v2/logs/lead-capture-debug.log

# Search for errors
grep -i "error" v2/logs/lead-capture-debug.log

# Search for specific lead
grep "LC1234567890" v2/logs/lead-capture-debug.log
```

### API Testing

```bash
# Test HubSpot connectivity
curl "http://localhost:8003/v2/api/lead-capture.php?debug_hubspot=test"

# Test form submission
curl -X POST http://localhost:8003/v2/api/lead-capture.php \
  -H "Content-Type: application/json" \
  -d '{"step":"1","name":"Test","phone":"+49123456789"}'
```

## Common Patterns

### Page Types

| Type | Time Delay | Scroll Threshold | Exit Intent |
|------|------------|-----------------|-------------|
| High Priority | 30s | 25-40% | 5s, 5% |
| Medium Priority | 30s | 40% | 8s, 10% |
| Low Priority | 60s | 40% | 10s, 20% |
| Blog Posts | 30s | 35% | 15s, 25% |

### Funnel Stages

- **TOF:** Tools, blog posts
- **MOF:** Industry, templates, downloads
- **BOF:** Pricing, comparison, product pages

### Trigger Types

- `time`: Time-based trigger
- `scroll-trigger`: Scroll-based trigger
- `exit-intent`: Exit intent trigger
- `manual`: Manual trigger
- `manual-callback`: Manual trigger (bypasses restrictions)

## Troubleshooting Quick Fixes

### Popup Doesn't Appear

```javascript
// Clear submission flags
localStorage.removeItem('lead_capture_submitted');
sessionStorage.removeItem('lead_capture_shown');
window.resetLeadCapture();
```

### Form Submission Fails

1. Check network tab for API errors
2. Check `v2/logs/lead-capture-debug.log`
3. Verify API endpoint accessible: `/v2/api/lead-capture.php`

### Copy Doesn't Match

1. Check URL pattern in `lead_capture_copy.php`
2. Add pattern if missing
3. Add to quick lookup for performance

### HubSpot Sync Issues

1. Test connectivity: `/v2/api/lead-capture.php?debug_hubspot=test`
2. Check API token in `lead-capture.php`
3. Verify form GUID matches HubSpot form

### Google Sheets Sync Issues

1. Check credentials file: `v2/config/google-sheets-credentials.json`
2. Verify service account has edit access
3. Check spreadsheet ID matches

## Related Documentation

- [Architecture](./ARCHITECTURE.md) - System overview
- [Integration Guide](./INTEGRATION_GUIDE.md) - Adding popup
- [Trigger Configuration](./TRIGGER_CONFIGURATION.md) - Customizing triggers
- [Copy Management](./COPY_MANAGEMENT.md) - Managing copy
- [Troubleshooting](./TROUBLESHOOTING.md) - Common issues
- [Testing Checklist](./TESTING_CHECKLIST.md) - Testing procedures
- [HubSpot Workflow](./HUBSPOT_WORKFLOW.md) - HubSpot integration
- [Google Sheets Workflow](./GOOGLE_SHEETS_WORKFLOW.md) - Google Sheets integration