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

# Heap Integration (Alpha)

> Connect BuildBetter with Heap for automatic user behavior tracking and analysis

<Note>
  **Coming Soon - Request Early Access**

  This integration is currently in Alpha development and not yet publicly available. If you're interested in early access, please contact [support@buildbetter.app](mailto:support@buildbetter.app) with "Heap Integration Early Access" in the subject line.
</Note>

Integrate BuildBetter with Heap to automatically capture every user interaction in your workspace without manual instrumentation. Gain insights into user behavior patterns and optimize your workflows.

## Features

* **Auto-Capture**: Track all user interactions automatically without tagging
* **User Identification**: Map BuildBetter users to Heap identities
* **Custom Events**: Define specific BuildBetter actions to track as events
* **Retroactive Analysis**: Analyze historical data even for newly defined events
* **Funnel Analysis**: Track workflow completion rates and drop-offs

## Setup Instructions

### Prerequisites

* An active BuildBetter account
* A Heap account with project ID
* Admin access to both platforms

### Connecting Heap

1. Go to **Settings → Integrations** in your BuildBetter dashboard
2. Select **Heap** from the analytics integrations
3. Enter your Heap Environment ID (found in your Heap project settings)
4. Choose data collection options:
   * Auto-capture all events (recommended)
   * Custom event selection
   * User identification details
5. Click **Connect** to activate the integration

### Setting Up Event Definitions

After connecting:

1. Log in to your Heap dashboard
2. Go to **Define Events**
3. Use Heap's Event Visualizer to select specific BuildBetter interactions
4. Name and categorize your events
5. Save your event definitions

## Usage

### Auto-Captured Events

Heap automatically tracks these BuildBetter interactions:

* Page views
* Button clicks
* Form submissions
* Input field interactions
* Navigation actions
* Modal interactions
* Video player controls

### Custom Event Tracking

For more specific BuildBetter events:

1. Go to **Settings → Integrations → Heap → Custom Events**
2. Define business-specific events like:
   * Call completed
   * Document generated
   * AI summary viewed
   * Project created
   * Folder organized
   * Chat thread started
3. Save your custom event configuration

### User Identification

BuildBetter sends these user identifiers to Heap:

* User ID (as Heap identity)
* Email
* Name
* Organization
* Role
* Signup date
* Subscription tier

### Creating Reports

Once your data is flowing to Heap:

1. Use **Analyze** in Heap to create reports
2. Build funnels to track workflow completion rates
3. Create user segments based on behavior
4. Set up dashboards for key BuildBetter metrics

## Troubleshooting

### Connection Issues

* Verify your Heap Environment ID is correct
* Check for browser extensions or content blockers interfering
* Ensure proper domain settings in Heap

### Missing Data

* Verify the integration is active
* Check user identification settings
* Review any custom event definitions for errors

### Multiple User Identities

* Check for inconsistent identification across sessions
* Review user merging settings in Heap
* Ensure consistent user ID generation in BuildBetter

## Data Management

* Set appropriate data retention policies in Heap
* Review privacy implications of auto-capture
* Consider enabling PII protection features for sensitive data