Jarhead for Craft CMS

Installation

Requirements

  • Craft CMS 5.3 or later
  • PHP 8.2 or later
  • A Hotjar account, and the Site ID for the site you want to record

No database tables, no runtime dependencies beyond Craft's own, and no build step.

Install

composer require justinholtweb/craft-jarhead
php craft plugin/install jarhead

Or find Jarhead in the Plugin Store and install it from there.

Find your Hotjar Site ID

In Hotjar, open Settings → Sites & Organizations. Each site has a numeric ID next to it — seven digits, something like 1234567. That number is the only thing Jarhead needs.

It is not a secret. It appears in the page source of every site running Hotjar, which is why it is safe to keep in an environment variable rather than a vault.

Switch it on

Go to Settings → Plugins → Jarhead and paste the Site ID into the box for your Craft site.

That is the whole of the required configuration. Every front-end HTML page now carries the Hotjar Tracking Code, spliced in before </head>, with no template change.

Do this before you deploy

Two settings on that same screen are worth setting now rather than after the first surprise.

Restrict the environments

// config/jarhead.php
return [
    'siteIds' => ['default' => '$HOTJAR_SITE_ID'],
    'allowedEnvironments' => ['production'],
];

Leave the allowlist empty and every environment sends to Hotjar — your laptop, staging, a client's UAT box — all into the same account, with nothing in the data to tell them apart. This is the single highest-value setting on the screen.

A $HOTJAR_SITE_ID that is not set in a given environment reads back as "not configured here", never as the literal string, so the same project config is correct everywhere.

Decide about consent

Session recording is personal data — it is a video of somebody using your site. Out of the box Jarhead loads Hotjar for every visitor on the first page view. If that is not what you want, set a consent gate before you go live; see Configuration.

Check it worked

Utilities → Hotjar answers the three questions, in the order they get asked:

  1. Is it configured? Every Craft site, its resolved Site ID, and whether that site is being tracked right now.
  2. Does Hotjar know this ID? Press Verify. Jarhead asks Hotjar's CDN for the tracking script belonging to your Site ID and reads the answer properly — Hotjar returns 200 for every numeric ID, so a wrong ID looks like success unless something checks the body.
  3. Why is it not on that page? Type any URI and get back the first rule that applied.

From the command line:

php craft jarhead/status                 # what each site would do right now
php craft jarhead/verify                 # ask Hotjar whether the Site IDs exist
php craft jarhead/explain checkout/cart  # why that URI is or is not tracked

php craft jarhead/status --strict exits non-zero when a site that should be sending is not, which makes it a post-deploy check rather than something a stakeholder tells you about.

If nothing appears in the page source

In order of likelihood:

  • devMode is on. Jarhead does not track while devMode is on unless you tell it to. This is deliberate — your own refreshes are not user research, and Hotjar bills by session.
  • You are signed in as an admin. Admins are excluded by default.
  • The environment is not in the allowlist.

php craft jarhead/explain names whichever it is. See Troubleshooting for the rest.