How to migrate from Heap to Pug
A practical path off Heap. Pug matches the autocapture-first core — trends, funnels, retention, flows, and profiles — open source and self-hostable. History doesn’t transfer between tools, so the playbook is to run both during cutover and switch once Pug covers the reports you rely on.
What you’ll need
- A Pug deployment — self-hosted, or the free cloud beta
- Access to your app’s tracking code (where Heap’s snippet/SDK lives)
- A short list of the Heap reports and events your team relies on
New to Pug? The Pug vs Heap comparison covers what matches and what doesn’t, and Heap pricing, explained covers why teams move. Pug is in open beta — features are live while we harden for general availability.
Migrating, in six steps
- 1
Inventory what you actually use in Heap
Heap autocaptures far more than any team looks at. Before moving, list the reports, funnels, retention cohorts, and defined events your team genuinely relies on. That short list — not Heap’s full surface — is what you need to reproduce, and it keeps the migration small.
- 2
Stand up Pug
Self-host Pug on a single Go binary backed by PostgreSQL, ClickHouse, and NATS, or start on the free cloud beta to skip ops entirely. Both run the same code, and you can move from cloud to self-hosted later without changing your tracking.
- 3
Swap the SDK and initialize
Where Heap’s snippet or SDK lives today, add the Pug Web, Flutter, or Node SDK and call init() with your project ID, public key, and endpoint. Autocapture — page views, clicks, scrolls, form submits, plus rage and dead clicks — starts immediately, so your baseline interactions are covered without re-instrumenting.
- 4
Recreate identify() and your key events
Call identify(userId) where you identify users in Heap so anonymous history merges into one profile, and add back the handful of custom events and traits your reports depend on. Standard, typed event names keep the data clean — the tracking-plan tools can scaffold them.
- 5
Run Pug alongside Heap
Analytics history doesn’t transfer between tools, so dual-run. Pug starts collecting the day you install it; keeping both live for a few weeks builds up comparable history and lets you check Pug’s numbers against Heap’s before you trust them.
- 6
Rebuild your insights, then cut over
Recreate that short list of reports in Pug — trends, funnels, retention, user-flow analysis — and confirm they match. Once the dashboards your team relies on are covered, make Pug the source of truth and retire Heap. There’s no rip-and-replace and your raw events are exportable from day one.
Migration questions, answered.
Can I import my Heap data into Pug?
No — there’s no direct importer, and analytics history doesn’t transfer between tools. Pug starts collecting the moment you install it. Keep Heap (or a warehouse export of it) read-only for historical reference, and dual-run so you build comparable history in Pug before switching.
How long does migrating from Heap take?
Swapping the SDK is usually an afternoon, because autocapture covers your baseline interactions immediately. The real work is rebuilding the handful of reports you actually use and dual-running long enough to trust them — most teams overlap a few weeks.
Will I lose any data?
No. Your Heap data stays in Heap; adding Pug deletes nothing. Pug simply starts a fresh collection in parallel. Plan the overlap so you’re never blind during cutover.
Is Pug a drop-in replacement for Heap?
No, and we won’t pretend otherwise. Pug matches Heap’s autocapture-first core — trends, funnels, retention, user flows, and unified profiles — but it doesn’t have retroactive event definition, session replay, or the wider Contentsquare suite. See the Pug vs Heap comparison for where each one wins.
Do I have to self-host Pug?
No — the managed cloud is free during open beta, so you can migrate without running infrastructure. Self-host whenever you want to own the data fully; it’s the same product either way, free forever under AGPL-3.0.
Own your analytics after the switch
Self-host Pug free under AGPL-3.0, or start on the free cloud beta. Either way it’s autocapture-first product analytics, with your raw events exportable from day one.