Install analytics on WordPress

It takes about 5 minutes: you install a free plugin that adds code to your site's head, paste one piece of code, and check that events are coming in.

Before you start

1. You need to be able to install plugins. On a self-hosted WordPress site you can. On WordPress.com you need a paid plan: Personal, Premium, Business or Commerce. Free WordPress.com sites cannot add header code.
2. You need your HeyCatch project key. It starts with hck_pk_.

1. Find your project key

Your project key starts with hck_pk_. Before your first install is confirmed it sits on the Analytics, Install screen in the sidebar; once an install is confirmed it sits behind the gear icon in the top right of the Product page. Press Copy prompt, paste the text into a note and copy just the key, from hck_pk_ to its last character. If a full stop follows the key, leave it out.

2. Copy this code

Replace YOUR_PROJECT_KEY with your key and keep the quotes:

<script type="module">
  import { analytics } from 'https://esm.sh/@heycatch/sdk@0.8.0';
  analytics.init({
    projectKey: 'YOUR_PROJECT_KEY',
    requestBatching: false,
    install: { framework: 'wordpress', agent: 'other' },
  });
</script>

Keep requestBatching: false. WordPress sites load a new page on every click, and without that line visits from iPhones get lost.

3. Install the WPCode plugin

1. In your WordPress dashboard, go to Plugins, then Add New.
2. Search for WPCode. Its full name also mentions Insert Headers and Footers.
3. Press Install Now, then Activate.

Already use another plugin for header code? Paste the code there instead, in the header, not the footer.

4. Paste the code

1. Go to Code Snippets, then Header & Footer.
2. Paste the code into the Header box.
3. Press Save Changes.

The change is live as soon as you save. There is no separate publish step.

5. Visit your live site

Open your live site in a normal browser, logged out or in a private window, and click around for a few seconds. Visits from bots, scripts and automated browsers are filtered out, so it has to be you, clicking.

6. Check in HeyCatch

Back in HeyCatch, on the screen where you copied the prompt, press "I've installed" within the next half hour. The check only counts events from the last 30 minutes, so do it straight after your visit.

Not seeing events?

1. Do you use a caching plugin or a CDN? Clear its cache, then visit the site again. An old cached page does not have the new code.
2. Do you use JavaScript optimisation? Exclude the HeyCatch code from delay or combining.
3. Is the key right? It starts with hck_pk_ and sits inside the quotes, with no extra spaces.
4. Is it in the Header box? Not the Body or Footer box.
5. Is the code there only once? Added twice, every event is counted twice.
6. Did you visit the live site yourself? Not a testing tool, and with any ad blocker switched off.

Still stuck? Write to us in the chat and we will look at your site.

Good to know

Purchases and order values in a shop need extra custom work. This guide covers visits, pages and clicks.

Short links

Short links are a separate step. Each link needs one redirect rule on your site, from /i to /?utm_campaign=i for each letter you use. On WordPress, add it with a redirect plugin or at your host, then open the short link: it should land on your home page. If it opens an old post instead, the rule is not in place yet: WordPress has guessed a post whose address starts with that letter, and that visit is not attributed. If you cannot add the rule, share the full link instead, https://yoursite.com/?utm_campaign=i, which is counted the same way. The Short links article explains the rule.