Docs · install guide

Install in one line.

1. Add the script

Put this in the <head> of every page. Your site key is on your site's settings page.

<script async crossorigin="anonymous"
        src="https://app.clickvitals.com/s/YOUR_SITE_KEY.js"></script>

• async: it never blocks rendering.
• crossorigin="anonymous": lets returning visitors download updates as tiny dictionary deltas (often under 100 bytes) and gives clearer error reports. It's safe: our CDN always sends the CORS header it needs.
• No cookie banner changes. The script stores nothing on the device.

2. Mark the areas you care about (optional)

Name a page area with data-cv-region, and give items an ID with data-cv-item:

<section data-cv-region="related-articles">
  <a href="/blog/a/" data-cv-item="article:123">…</a>
  <a href="/blog/b/" data-cv-item="article:456">…</a>
</section>

<div data-cv-region="product-carousel">
  <a href="/p/kb-1/" data-cv-item="product:KB-1">…</a>
</div>

Without attributes, every link click is still recorded. The region comes from the nearest nav, header, footer, aside or main, and the position from its order within that region.

3. Content IDs (usually automatic)

Each page view is matched to a piece of content automatically. The first of these that's present wins:

1. an explicit clickvitals('page', { id, type, category }) call
2. <meta name="cv:content-id" content="article:123"> (plus optional cv:content-type and cv:category)
3. JSON-LD (Article, Product, BlogPosting…), with the category taken from BreadcrumbList
4. the canonical URL, then the page path

4. The clickvitals() API

Queue calls before the script loads with this one-liner, then call it anywhere:

<script>window.clickvitals=window.clickvitals||function(){(clickvitals.q=clickvitals.q||[]).push(arguments)}</script>

clickvitals('page', { id: 'article:123', type: 'Article', category: 'Guides' });
clickvitals('label', 'article');            // group pages by template
clickvitals('data', 'ab_test', 'variant-b'); // up to 50 custom key/values per page view

Single-page apps & HTMX

Nothing to configure. History API route changes (pushState, popstate) start a new page view automatically. If your framework only updates part of the page, put your JSON-LD or cv:content-id meta tag inside the part that changes, or call clickvitals('page', …) after each navigation.

Serving it from your own domain (recommended at scale)

Proxy /_cv/* through your CDN to ours. The script and beacons then come from your own domain: no extra DNS lookup or TLS connection, and fewer losses to blockers.