> ## Documentation Index
> Fetch the complete documentation index at: https://funnelfox.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Hotjar integration: heatmaps & recordings

> Add Hotjar to your FunnelFox funnels for heatmaps, session recordings, and user behavior analysis. Optimize conversion rates visually.

Hotjar integration adds session recordings and heatmaps to your FunnelFox
funnels for visual behavior analysis.

## Features

* **Session Recordings**: Watch real user sessions
* **Heatmaps**: See where users click, move, and scroll
* **Conversion Funnels**: Visualize drop-off points
* **Feedback Widgets**: Collect user feedback
* **Rage Click Detection**: Identify frustration points
* **Form Analysis**: Understand form abandonment

## Configuration

### Prerequisites

* Active Hotjar account
* Hotjar Site ID
* FunnelFox project with funnels ready to publish

<Warning>
  FunnelFox currently supports integration with [https://insights.hotjar.com/](https://insights.hotjar.com/) only.

  Integrating with  [https://app.contentsquare.com/](https://app.contentsquare.com/) is not available yet.
</Warning>

### Setup Steps

<Steps>
  <Step title="Get Hotjar Site ID">
    1. Log into [Hotjar](https://www.hotjar.com)
    2. Go to **Sites & Organizations**
    3. Select your site
    4. Copy the **Site ID** (6-7 digit number)

    <Info>
      The Site ID is also visible in your Hotjar tracking code as
      `hjid:1234567`
    </Info>
  </Step>

  <Step title="Configure in FunnelFox">
    1. Go to **Integrations** → **Hotjar**
    2. Toggle **Hotjar** on
    3. Enter your **Site ID**
    4. Click **Save changes**
  </Step>

  <Step title="Republish Funnels">
    [Republish your funnels](/editor/publishing) to activate Hotjar
  </Step>

  <Step title="Verify Installation">
    1. Open your funnel
    2. Check Hotjar dashboard
    3. Look for incoming sessions
    4. May take 5-10 minutes to appear
  </Step>
</Steps>

## Session Recordings

### What's Captured

Hotjar records:

* Mouse movements and clicks
* Scroll behavior
* Form interactions
* Page transitions
* Rage clicks (repeated clicking)
* U-turns (back navigation)

### Privacy Features

Hotjar automatically:

* Masks sensitive input fields
* Excludes password fields
* Suppresses credit card numbers
* Respects user privacy settings

<Warning>
  Review recorded sessions to ensure no sensitive data is visible.
  Add suppression rules if needed.
</Warning>

### Filtering Sessions

Find relevant recordings by:

* **Page URL**: Specific funnel pages
* **User behavior**: Rage clicks, u-turns
* **Technology**: Device, browser, OS
* **Traffic source**: Referrer, UTM parameters
* **Events**: Custom JavaScript events

## Heatmaps

### Types of Heatmaps

1. **Click Maps**: Where users click/tap
2. **Move Maps**: Mouse movement patterns
3. **Scroll Maps**: How far users scroll
4. **Engagement Zones**: Combined interaction data

### Creating Heatmaps

<Steps>
  <Step title="Generate Heatmap">
    1. In Hotjar, go to **Heatmaps**
    2. Click **New Heatmap**
    3. Enter your funnel URL
    4. Select device types to track
    5. Wait for data collection (100+ pageviews recommended)
  </Step>

  <Step title="Analyze Results">
    Look for:

    * Unexpected click areas (indicates confusion)
    * Ignored CTAs (poor visibility)
    * Scroll depth (content engagement)
    * Mobile vs. desktop differences
  </Step>
</Steps>

## Conversion Funnels

While FunnelFox has built-in analytics, Hotjar funnels provide visual context:

1. Define funnel steps using page URLs
2. See drop-off between steps
3. Watch recordings of users who dropped off
4. Identify common abandonment patterns

## Feedback Collection

### On-Site Surveys

Deploy surveys on specific pages:

* Exit intent surveys
* Post-purchase feedback
* NPS scores
* Custom questions

### Feedback Widget

Trigger feedback widgets from your custom code:

```javascript theme={null}
// Add this to your funnel's custom code to trigger feedback:
if (window.hj) {
  hj('trigger', 'funnel_feedback');
}
```

## Advanced Configuration

### Custom Events

Add custom tracking in your funnel code:

```javascript theme={null}
// Use these in your funnel's custom code for specific tracking:
if (window.hj) {
  // Virtual page view for dynamic content
  hj('vpv', '/virtual/checkout-step-2');
  
  // Trigger specific recording
  hj('trigger', 'high_value_user');
  
  // Tag recordings
  hj('tagRecording', ['completed_purchase']);
}
```

### Suppression Rules

Exclude sensitive content:

1. Go to **Settings** → **Privacy**
2. Add CSS selectors to suppress
3. Common suppressions:
   * `[data-sensitive="true"]`
   * `.credit-card-input`
   * `#social-security`

### Sampling Rate

Control recording volume:

* Default: Records all sessions
* High traffic: Sample 10-20%
* Testing: Record 100%

Adjust in Hotjar dashboard under site settings.

## Integration with Analytics

Combine Hotjar with quantitative analytics:

1. **Identify Issues**: Find drop-off in analytics
2. **Watch Sessions**: See why users leave
3. **Create Heatmaps**: Understand behavior patterns
4. **Test Solutions**: Measure improvements

## Troubleshooting

<AccordionGroup>
  <Accordion title="No recordings appearing">
    * Verify Site ID is correct
    * Check funnels were republished
    * Ensure Hotjar is not blocked by ad blockers
    * Wait 10-15 minutes for processing
    * Check daily session limit hasn't been reached
  </Accordion>

  <Accordion title="Incomplete recordings">
    * Check if user navigates to external sites
    * Verify all pages have Hotjar installed
    * Look for JavaScript errors in console
    * Ensure cookies are enabled
  </Accordion>

  <Accordion title="Missing heatmap data">
    * Need minimum 100 pageviews for heatmaps
    * Check URL matches exactly (including parameters)
    * Verify device type filter settings
    * Wait for data processing (can take hours)
  </Accordion>

  <Accordion title="Privacy concerns">
    * Add suppression rules for sensitive elements
    * Exclude specific pages from recording
    * Use data suppression for logged-in areas
    * Review privacy settings regularly
  </Accordion>
</AccordionGroup>

## Using Hotjar Effectively

* Watch 10-20 session recordings before making changes
* Focus on pages with high drop-off rates
* Validate insights with A/B testing
* Schedule regular session review sessions
* Tag interesting behaviors for later review
* Share recordings with your team

## Limitations

* No event tracking (visual only)
* Limited API access
* Session limits based on plan
* 365-day data retention
* No real-time recordings

## Optimizing Hotjar Usage

* Set appropriate sampling rates for your traffic volume
* Focus recording on key conversion pages
* Archive important sessions before they expire
* Regularly clean up old heatmaps

## Next Steps

* [Set up conversion tracking](/integrations/analytics#standard-events)
* [Configure A/B tests](/dashboard/experiments) to validate insights
* [Watch Hotjar tutorials](https://www.hotjar.com/academy/) for advanced features