Installing the analytics SDK

How to install, how to tell it worked, when data appears, and what it changes on your site.

How do I install the analytics SDK?#

Open Analytics. Until your first install is confirmed, Install is an item in the Analytics sidebar and the install panel lives on that screen. Once an install is confirmed, the panel sits behind the gear icon in the top right of the Product page. Either way, the panel has two sections, Web app / Website and Mobile app, each with its own Installed or Not installed status. Open the one you are installing, pick your framework, press "Copy prompt" and paste it into your AI builder or coding agent. The ones named on that screen are Claude Code, Cursor, Codex, Lovable, Bolt, v0 and Replit, and the Framework row lists React, Next.js, Vue, Svelte, Astro, Angular and Plain JavaScript for the web, and React Native, Swift, Kotlin and Flutter for mobile. The prompt is not limited to that row: on the web it works with any framework, or plain HTML with no build step. Both sections use the same project key.

If your site is on a website builder, WordPress, Webflow, Wix, Squarespace, Shopify or Framer, the same screen has a line for it under the Framework row, with a link, Open the setup guide. The same step-by-step guides, one per builder, are in this help centre under Analytics install guides.

What the button copies is not a snippet of code. It is one instruction line that points your builder at our public install guide and carries your own project key, so the builder does the install and reports back.

Then publish your site, open it and click around to generate events, and press "I've installed" within the next half hour, because the check only counts events from the last 30 minutes.

Where did Install and Dashboard go?#

The Analytics section of the sidebar holds Product and Short links, plus Install until your first install is confirmed.

After your first install is confirmed, the install details, including the project key and the install check, sit behind the gear icon in the top right of the Product page.

Dashboard is simply called Product now, with the same metrics, summary and funnel. At the top of it there is a tab per surface, Web app / Website and your mobile app, with + Add mobile app in place of the second tab until the app is installed.

How do I know the install worked?#

Press "I've installed" and the button goes to "Verifying" with "Checking your install...". A pass shows "Connected. You're good to go." and the section's status changes from Not installed to Installed. A failure shows "Couldn't verify your install. Please try again."

The important part is that window: the check only counts events from the last 30 minutes, and that is the whole window rather than a rounding. A perfectly good install reports as failed if you press the button the next morning, or on activity from yesterday, and the message does not say why. So publish the site, open it and click around for about 30 seconds, then press "I've installed" within the next half hour.

There is a quicker check you can run yourself. Open your live site and look at the browser console: a working install prints a line like [HeyCatch] SDK v0.8.0 (prod) initialized. If that line is not there, the SDK never loaded. If it reads dev where this one reads prod, the version you have came from our development channel and needs replacing with the plain one.

How long before data appears in the dashboard?#

Give it about 30 minutes before the dashboard is worth looking at.

Do not confuse that with the install check, which is immediate but only counts events from the last 30 minutes. Click around your site, verify straight away, then come back to the dashboard about 30 minutes later.

If 30 minutes have passed and it is still empty, ask us here instead of waiting longer. We can see whether any events have ever arrived from your site, and waiting does not fix an install that is not sending.

I installed the SDK but pressing "I've installed" says no events were seen. What is wrong?#

The failure reads "Couldn't verify your install. Please try again.", and it almost always means the check found no events from your site in the last 30 minutes. It is about the window the check looked at, not a verdict on your code. Two things cause almost all of these. 1. The change is not actually deployed. The SDK only reports from your live site, so an edit you have not published yet produces nothing. 2. The check only looks at the last 30 minutes, so a correct install verifies as failed if you press the button on older activity. A third, rarer one: the site was opened by an automated browser, a testing tool or a coding agent rather than by you. Those visits are filtered out as bot traffic, so nothing arrives.

Do it in this order. 1. Publish the site with the SDK on it. 2. Open the live site and click around for about 30 seconds. 3. Press "I've installed" within the next half hour.

A pass reads "Connected. You're good to go." and the status turns to Installed. The dashboard itself needs about 30 minutes after the first events land.

Does installing the SDK change my build scripts, environment variables, CI or middleware?#

No. No environment variables, no build script changes, no CI changes, no middleware.

What it touches: your package manifest, one init call at your client entry point, and optionally identity calls in your sign-in and sign-out paths. Deployment config is touched only if you opt into short links, which adds a single redirect rule. Outgoing request headers are modified only for hosts you list yourself.

Will the analytics snippet slow my page down?#

It loads asynchronously, after the page has rendered, so it does not block anything on the page.

Can I run Google Analytics and HeyCatch analytics at the same time, or will events be double counted?#

You can run both. They are separate systems and do not interfere with each other, so nothing is double counted between them. The one thing to avoid is installing the HeyCatch snippet twice on the same site, because that does duplicate events.

Is HeyCatch still worth using if I do not install the analytics SDK?#

Yes. Without the SDK there is no analytics: no Product dashboard, funnels or recommendations, no users or session timelines, and no short links or channel attribution. Catches on Reddit, X and Threads, and the videos for Instagram, TikTok, YouTube and Facebook, all run without the SDK, off your connected accounts and your live site.

I do not want tracking inside my product. Can I install the SDK on my landing page only?#

Yes. Put it on the landing page and leave the product itself untouched. That is where a lot of the signal you care about lives anyway: who arrives, what they read and where they drop off before they ever sign up.