Add CLItrail to Hugo

Where the CLItrail tag goes in Hugo, in its own idiom, with the consent, CSP and client-side routing details and how to check it works.

Written for Hugo 0.146 and later (older layouts use layouts/partials/, which Hugo still maps)

#Where the tag goes

Edit layouts/_partials/head.html in your site (copy the theme's partial to the same path and edit the copy). Put the tag on every page that shows your install command; site-wide is best, after your existing analytics tags.

{{/* layouts/_partials/head.html: your copy of the theme's partial */}}
<script defer src="https://YOUR_SERVICE/browser.js" data-website="YOUR_WEBSITE_ID"></script>

#Only after consent

Use the loader in place of the tag: nothing from CLItrail loads until startClitrail() runs. Load the loader before your consent manager's script and call startClitrail() from the manager's accept callback (most managers also run it on later visits once a choice is stored; check yours). Use the marketing category when installs go to Google Ads, Meta, TikTok or X Ads, and the analytics category when they only reach GA4 or your webhooks.

Consent loader

// Loads CLItrail only after the visitor agrees. Call startClitrail() from your
// consent manager's "accepted" callback; nothing is fetched or stored before that.
window.startClitrail = () => {
  if (document.getElementById('clitrail')) return;
  const tag = document.createElement('script');
  tag.id = 'clitrail';
  tag.src = 'https://YOUR_SERVICE/browser.js';
  tag.dataset.website = 'YOUR_WEBSITE_ID';
  document.head.append(tag);
};

<script defer src="{{ "clitrail-consent.js" | relURL }}"></script>

#Client-side routing

Every page is a full page load, so the tag records each page by itself. Nothing else to add.

#Content Security Policy

The build is static files, so the policy lives in your host's header settings (for example _headers on Cloudflare Pages or Netlify, or vercel.json): add https://YOUR_SERVICE to script-src and connect-src, and blob: to worker-src (only Safari before 26 needs that one). [server.headers] in your Hugo config only applies to hugo server.

script-src 'self' https://YOUR_SERVICE;
connect-src 'self' https://YOUR_SERVICE;
worker-src 'self' blob:;

#Verify it works

1. Run hugo server (http://localhost:1313) or deploy.
2. Open a page with the tag in Chrome or Firefox (accept analytics first if you gate CLItrail on consent), open the developer console and run await InstallAttribution.ready. It resolves to { ok: true, urlId, hasAnalyticsContext, expiresAt }.
3. In the CLItrail dashboard, open Visits & identities: the visit is listed.
4. Anything else names the cause: disabled (no consent yet, or data-enabled="false"), opfs_unavailable (the page is not served over https or from localhost), Error (the service refused the visit: add the page's origin, including a development origin such as http://localhost:3000, under Settings → Additional domains). If InstallAttribution is undefined, the tag did not load: check the Network tab and your Content-Security-Policy.

Then run your installer on the same computer and check Install events, or run the hook with --doctor.

#Notes

• Never edit the theme in place: a file at the same path in your site's layouts/ wins.
• Many themes offer a hook partial for this, such as extend_head.html or custom_head.html: use it when yours has one.

Hugo documentation: gohugo.io/templates/new-templatesystem-overview

Using other install paths or destinations? The setup generator puts this snippet together with your hooks and destination checklist.