Recap

Heap Analytics is a digital product analytics platform that automatically captures user interactions without requiring manual event tracking. Unlike traditional analytics, Heap's web SDK is installed via a script snippet (not an NPM package) and can be configured to capture IP addresses for visitor identification—especially useful for detecting suspicious traffic patterns.

Real Example: This digital garden uses Heap to track anonymous visitors and identify suspicious repeated access from specific locations by enabling IP autocapture.

Why Heap Analytics?

Automatic Event Tracking

Traditional analytics (like Google Analytics) require you to manually instrument every event you want to track. Heap automatically captures all user interactions:

• Page views
• Clicks
• Form submissions
• Input changes
• Navigation patterns

Retroactive Analysis

Since Heap captures everything, you can define events retroactively. If you realize you want to track button clicks from 3 months ago, the data is already there.

Anonymous User Tracking

Heap automatically assigns unique IDs to anonymous users and maintains their journey across sessions via cookies—no authentication required.

Installation Methods

No Official NPM Package for Web

Important: Heap does NOT have an official NPM package for web applications. The official installation method is via script injection.

Available NPM Packages (What They're For):

• @heap/react-native-heap - Official React Native SDK
• heap-api - Server-side API client for Node.js (not for browser)
• reactjs-heap - Community package (not officially maintained)
• Package named heap - UNRELATED (it's a binary heap data structure)

Recommended Approach: Script-Based Installation

The official Heap installation uses a JavaScript snippet that loads asynchronously.

Next.js Implementation

Step 1: Create HeapAnalytics Component

Create a client component in domains/garden-components/heap-analytics.tsx:

1"use client";
2
3import Script from "next/script";
4
5export const HeapAnalytics = () => {
6  const heapAppId = process.env.NEXT_PUBLIC_HEAP_APP_ID;
7
8  // Only load Heap if the environment variable is set
9  if (!heapAppId) {
10    return null;
11  }
12
13  return (
14    <Script
15      id="heap-analytics"
16      strategy="afterInteractive"
17      dangerouslySetInnerHTML={{
18        __html: `
19          window.heapReadyCb=window.heapReadyCb||[],window.heap=window.heap||[],heap.load=function(e,t){window.heap.envId=e,window.heap.clientConfig=t=t||{},window.heap.clientConfig.shouldFetchServerConfig=!1;var a=document.createElement("script");a.type="text/javascript",a.async=!0,a.src="https://cdn.us.heap-api.com/config/"+e+"/heap_config.js";var r=document.getElementsByTagName("script")[0];r.parentNode.insertBefore(a,r);var n=["init","startTracking","stopTracking","track","resetIdentity","identify","identifyHashed","getSessionId","getUserId","getIdentity","addUserProperties","addEventProperties","removeEventProperty","clearEventProperties","addAccountProperties","addAdapter","addTransformer","addTransformerFn","onReady","addPageviewProperties","removePageviewProperty","clearPageviewProperties","trackPageview"],i=function(e){return function(){var t=Array.prototype.slice.call(arguments,0);window.heapReadyCb.push({name:e,fn:function(){heap[e]&&heap[e].apply(heap,t)}})}};for(var p=0;p<n.length;p++)heap[n[p]]=i(n[p])};
20          heap.load("${heapAppId}");
21        `,
22      }}
23    />
24  );
25};

Key Details:

• "use client" directive required for Next.js client component
• Uses Next.js Script component with strategy="afterInteractive" for optimal loading
• Conditionally loads only when environment variable is set
• Prevents analytics data pollution in development

Step 2: Add Environment Variables

Create .env.local (gitignored by default in Next.js):

1# Heap Analytics
2# Get your App ID from: https://heapanalytics.com/app/settings/projects
3NEXT_PUBLIC_HEAP_APP_ID=your-app-id-here

Create .env.local.example for team reference:

1# Heap Analytics
2# Leave empty to disable Heap Analytics
3NEXT_PUBLIC_HEAP_APP_ID=

Step 3: Integrate into Layout

Add the component to your app/layout.tsx:

1import { HeapAnalytics } from "@/domains/garden-components/heap-analytics";
2
3export default function RootLayout({ children }) {
4  return (
5    <html lang="en">
6      <body>
7        <HeapAnalytics />
8        {/* Rest of your app */}
9      </body>
10    </html>
11  );
12}

User Identification Strategies

Option 1: Anonymous Tracking (Recommended for Content Sites)

Don't call heap.identify() at all. Heap will automatically:

• Assign unique anonymous user IDs
• Track sessions across visits (via cookies)
• Maintain user journeys
• Provide all analytics without collecting PII

Best for: Blogs, digital gardens, marketing sites

Option 2: Authenticated User Tracking

For applications with user authentication, identify users after login:

1useEffect(() => {
2  if (session?.user?.email) {
3    window.heap?.identify(session.user.email);
4    window.heap?.addUserProperties({
5      name: session.user.name,
6      userId: session.user.id,
7    });
8  }
9}, [session]);

IP Address Tracking

Default Behavior

By default, Heap does NOT capture IP addresses. It collects:

• ✅ Geolocation (city/country level)
• ✅ Anonymous user IDs
• ✅ Device and browser information
• ❌ IP addresses (disabled for privacy)

Enabling IP Autocapture

To track IP addresses (useful for identifying suspicious traffic):

1. Navigate to your Heap dashboard
2. Go to Account > Manage > Privacy & Security
3. Enable the "IP Autocapture" toggle
4. Confirm your choice in the popup

Important: This setting is per-environment (development/production separate).

Use Case: Identifying Suspicious Traffic

If your analytics shows repeated suspicious access from specific locations (e.g., unexplained Singapore traffic on an unpromoted site), enabling IP autocapture allows you to:

• See actual IP addresses of visitors
• Identify patterns or bot traffic
• Cross-reference with other analytics platforms
• Block malicious IPs if needed

Content Security Policy (CSP)

If your site uses CSP headers, authorize these domains:

For US data centers:

• cdn.us.heap-api.com
• c.us.heap-api.com
• heapanalytics.com

For EU data centers: Check Heap documentation for regional endpoints.

Verification

Check Installation in Browser Console

1// Check if Heap loaded
2window.heap
3
4// Check SDK version (should be 5.x.x)
5heap?.getConfig?.().sdk?.version || heap.version.heapJsVersion
6
7// Get current user ID
8heap.getUserId()
9
10// Get session ID
11heap.getSessionId()

Common Issues

Heap not loading:

• Verify NEXT_PUBLIC_HEAP_APP_ID is set correctly
• Check browser console for CSP violations
• Ensure script strategy is afterInteractive or lazyOnload

TypeScript errors:

• Add type declaration for window.heap if needed
• Use optional chaining: window.heap?.identify()

Privacy Considerations

GDPR Compliance

• Anonymous tracking is generally GDPR-compliant
• IP address collection may require user consent in EU
• Provide cookie consent banners if required by your jurisdiction

Data Retention

Configure data retention policies in Heap dashboard under Data Management settings.

User Opt-Out

Respect "Do Not Track" headers or provide opt-out mechanisms:

1// Stop tracking for a user
2window.heap?.stopTracking()
3
4// Resume tracking
5window.heap?.startTracking()

Advanced Configuration

Custom Events

Track specific actions:

1heap.track('Newsletter Signup', {
2  source: 'footer',
3  timestamp: new Date().toISOString()
4});

Event Properties

Add properties to all future events:

1heap.addEventProperties({
2  theme: 'dark',
3  language: 'en'
4});

User Properties

Attach metadata to user profiles:

1heap.addUserProperties({
2  accountType: 'premium',
3  signupDate: '2025-01-15'
4});

Comparison with Other Analytics

| Feature | Heap | Google Analytics | Mixpanel | |---------|------|------------------|----------| | Auto-capture | ✅ Yes | ❌ No | ❌ No | | Retroactive events | ✅ Yes | ❌ No | ❌ Limited | | IP tracking | ⚙️ Optional | ✅ Yes | ⚙️ Optional | | NPM package | ❌ No (web) | ✅ Yes | ✅ Yes | | User sessions | ✅ Automatic | ✅ Automatic | ⚙️ Manual |

Resources

• Official Heap Web Documentation
• Heap API Reference
• Privacy Features Guide
• Next.js Integration Tutorial