Installing Clicky (for AI agents)
Procedure for an agent installing Clicky on a website end to end. You will need the account
userkey (see the
API walkthrough for where it comes from and how to call the API). Everything here is read-only except the part you do to the website's own code, which is the user's repository, not their Clicky account.
0. Check if there's a compatible plugin for the website's platform
We have
web analytics plugins available for a variety platforms: WordPress, Shopify, etc. If one is available, this will typically be the easiest route to get tracking running. Some plugins have extra features such as
custom data tracking, but many only implement basic tracking. If you want to use advanced tracking features, a manual integration may be necessary.
1. Check whether the site already exists
List the account's sites and look for the hostname:
POST https://clicky.com/api/account/sites
userkey=USERKEY&output=json
The response includes each site's
site_id,
hostname, and
sitekey. If the site is there, note its
site_id and skip to step 3.
2. If it doesn't exist: the human adds it
Site registration is intentionally
human-only. There is no API endpoint for it. Ask the user to log in to
the dashboard and add the site there (the dashboard walks them through it). Then re-run step 1 to pick up the new
site_id.
Do not loop on this. Wait for the user to confirm they've added it.
3. Add the tracking code to the website
The canonical snippet (always take it from the
tracking code page, not from memory) is one line, placed site-wide immediately before the closing
</body> tag:
<script async data-id="SITE_ID" src="//static.getclicky.com/js"></script>
Replace
SITE_ID with the numeric
site_id from step 1. A Google Tag Manager variant is documented on that same page; use it if the user manages tags through GTM.
Before editing, check what you're editing into:
- Content-Security-Policy: if the site sends a CSP header, script-src must allow static.getclicky.com (and in.getclicky.com for the beacon, which loads via XHR/img). Adding the tag without widening the CSP = silently zero data. Search the repo (and any CDN/edge config) for Content-Security-Policy.
- Framework templates: in most frameworks the right slot is the shared layout, not individual pages (Next.js: a client component in the root layout, or next/script; Rails: app/views/layouts/; Django: the base template; WordPress: prefer the plugin over hand-editing the theme). One insertion in the shared layout beats 200 per-page insertions.
- Static site generators: edit the template/layout, rebuild, don't patch generated HTML by hand.
4. Verify
Have the user load a page of the site in a browser, then check the data landed:
POST https://clicky.com/api/stats/4
site_id=SITE_ID&sitekey=SITEKEY&type=visitors-online&output=json
A non-zero value within ~30 seconds means the install works (the site's live view is the human-friendly equivalent). Zero could also just mean nobody's on the site, so
type=visitors&date=today after a fresh page load is the stronger check.
Gotchas
- Ad blockers kill the script for a slice of visitors, which is a coverage gap, not a broken install. First-party proxy tracking is the fix, and it's documented at /help/reverse-proxy-web-analytics. Don't duplicate those instructions, link the user to that page.
- Do not add a second copy of the code to pages that already have it (check the crawl, not just one page). Double tags double-count.
- SPA sites: the one-liner only counts the first page load. The user needs the manual-pageview option from the custom tracking docs, which is a code change in their router, not a Clicky setting.
Privacy note
By default Clicky sets
no tracking cookies (visitor privacy is enabled per-site out of the box, and unique visitors are detected from a hashed IP fragment instead). That usually means no cookie-consent banner is required for Clicky alone, but consent obligations depend on the visitor's jurisdiction and everything
else on the site, so tell the user to confirm against
the privacy docs rather than trusting this paragraph as legal advice.
📢 Make better decisions with real-time insights
Sign up for Clicky now and transform your analytics