Heap's autocapture
Heap is useful because it captures broad user behavior before the team has perfectly modeled the schema. Product and growth teams can review clicks, form interactions, navigational steps, and other interface behavior retroactively, then decide which moments actually matter. That makes Heap especially strong early in a product lifecycle or inside fast-moving teams where instrumentation debt would otherwise block analysis.
TrackLayer should not compete with that broad capture layer. It should sit after it, at the moment where an observed action becomes a business event worth canonical treatment. In practice, Heap helps teams discover which user behaviors predict conversion, while TrackLayer receives the chosen milestones as `sign_up`, `begin_checkout`, `purchase`, `qualify_lead`, or other stable events that downstream systems can trust.
Setup
Install Heap and let autocapture do the broad collection
Start by deploying Heap on the site or app surfaces where you want broad product visibility. Heap should remain the wide net that records clicks, form interactions, page transitions, and session context without asking engineers to name every UI event in advance. This gives analysts room to investigate behavior first instead of freezing the schema too early.
Heap snippet loaded in web app
autocapture: enabled
environment: production
Goal
collect broad interaction data
without turning every click into a canonical business eventForward selected milestones into TrackLayer `/api/capture`
Do not mirror all Heap activity into TrackLayer. Instead, choose the small set of actions that deserve canonical downstream treatment, such as signups, checkout starts, purchases, qualified leads, or subscriptions. Send those to TrackLayer's `/api/capture` endpoint from your backend or trusted middleware so the activation layer stays deliberate and retry-safe.
POST /api/capture
Content-Type: application/json
{
"event": "purchase",
"event_id": "ord_10492_purchase",
"user_id": "cust_2048",
"anonymous_id": "anon_91b2",
"properties": {
"order_id": "ord_10492",
"value": 129.95,
"currency": "EUR"
},
"source": "heap"
}Keep identity handoff explicit with `identify`
Heap becomes more valuable once anonymous browsing and authenticated behavior merge into one user profile. TrackLayer needs the same handoff. On signup, login, checkout completion, or lead creation, send an explicit `identify` call so both systems resolve the same person. That keeps later server-side purchases tied to the same profile Heap used for cohorting and funnel analysis.
POST /api/identify
Content-Type: application/json
{
"user_id": "cust_2048",
"anonymous_id": "anon_91b2",
"traits": {
"email_sha256": "9d7c...e31a",
"plan": "pro",
"country": "DE"
}
}Validate one end-to-end event before expanding
Run a controlled test with one known user and one revenue or lead event. Confirm the event appears in Heap for analysis, then confirm the canonical version reaches TrackLayer with the same user anchor, timestamp, and business identifiers. Only after one event survives the full path cleanly should you widen the mapping or add more virtual events.
Validation path
Heap autocapture or virtual event
→ application or middleware promotion
→ TrackLayer /api/capture
→ downstream Meta / Google / CRM destination
Checks
1. same user_id
2. same order_id or lead_id
3. stable event_id
4. accepted downstream sendEvent mapping
Heap event names often start as UI descriptions or analyst-defined labels. That is fine for exploration, but the events leaving your analytics layer should collapse into a smaller canonical contract. The table below shows the common pattern: descriptive Heap events on the left, TrackLayer business events in the middle, and the activation intent on the right.
| Heap auto-event or label | TrackLayer canonical | Activation behavior |
|---|---|---|
| Button Clicked: Add to cart | add_to_cart | Send downstream when product, quantity, and value are known |
| Form Submitted: Signup | sign_up | Use as registration milestone for CAPI and CRM routing |
| Checkout Started | begin_checkout | Useful for ad optimization and funnel parity |
| Payment Info Completed | add_payment_info | Optional high-intent milestone when quality is strong |
| Order Completed | purchase | Primary revenue event with value, currency, and order ID |
| Lead Form Qualified | qualify_lead | Use for B2B routing once qualification rules pass |
Virtual events and schema control
Heap's virtual event definitions are powerful because analysts can define meaningful behaviors after the fact without waiting on a release cycle. That flexibility is a feature for product analysis, but it should not become an uncontrolled source of downstream activation names. If a virtual event starts influencing ads, remarketing, or CRM workflows, promote it into an explicit TrackLayer mapping instead of treating the Heap label itself as a permanent contract.
The working rule is simple. Heap owns discovery and fast iteration. TrackLayer's schema registry owns the stable production-facing vocabulary. A virtual event like "Clicked Start Trial CTA Twice" may be useful in Heap, but if it drives activation it should map intentionally to a canonical event such as `start_trial` plus supporting properties, not leak directly into every downstream integration.
Heap virtual event
"Lead Form Qualified in UI"
TrackLayer schema registry
source: heap
source_event: "Lead Form Qualified in UI"
canonical_event: qualify_lead
required_properties: lead_id, pipeline_stage
status: approvedCohort sync pattern
Heap cohorts are often the place where teams discover activation opportunities: users who started checkout but stalled, trial users with strong product usage, or accounts showing early churn risk. When those groups need to leave the analytics layer, TrackLayer is the clean relay. Export or mirror the cohort membership into TrackLayer, attach the shared user identity, and let TrackLayer decide which destinations should receive that audience.
The reverse direction can matter too. TrackLayer may calculate states Heap does not naturally own, such as high match quality, destination eligibility, or paid-channel classifications. Those can be synced back as traits so Heap analysts can segment funnels by downstream readiness or ad-quality state without moving delivery logic into Heap itself.
Heap cohort membership
→ shared user_id or account_id
→ TrackLayer audience record
→ Meta / Google / LinkedIn / CRM sync
TrackLayer computed trait
→ Heap user property
→ cohortable inside HeapCommon questions
Does TrackLayer replace Heap?
No. Heap remains the behavioral analytics layer, especially for retroactive analysis and UI-defined events. TrackLayer handles the smaller set of canonical events that need server-side activation, deduplication, and destination-specific delivery.
Should every Heap event be sent to TrackLayer?
Usually no. Heap captures a lot of useful exploratory behavior, but most of it should stay in analytics. Send only the actions that represent meaningful commercial milestones or durable identity changes.
What happens when Heap virtual event definitions change?
Treat virtual events as analytical definitions first. If a virtual event also drives activation, update the corresponding TrackLayer mapping or schema registry rule explicitly so downstream naming does not drift silently.
Why might Heap and ad platform counts still differ?
Heap shows the interaction stream you analyzed. Ad platforms show only the conversions they accepted, matched, and attributed under their own policies. TrackLayer makes the handoff cleaner, but it does not erase attribution differences.
Related implementation guides
Mixpanel integration
Compare Heap's autocapture model with a more explicitly instrumented product analytics stack.
Read guide →Identity resolution
Design the user keys that keep Heap cohorts and TrackLayer conversions attached to the same person.
Read guide →Dedup explained
Keep one customer action from becoming multiple downstream conversion events.
Read guide →