Add the tracker

This page shows the tag that makes Clear Saga count visits, and explains what to paste, where to paste it and what it does once it is there. If you want a walk through from a new account instead, start with the quick start.

The tag #

This is the whole installation. Paste it into your site once, with your own site key in place of YOUR_SITE_KEY.

<script
  defer
  data-site-key="YOUR_SITE_KEY"
  src="https://clearsaga.com/js/script.js"
></script>

Settings, Installation in the dashboard shows the same tag with your key already filled in, and a button to copy it. Every site has its own key.

Some platforms want the tag written in their own way. The attributes are the same in each of these:

import Script from 'next/script'

<Script
  id="clearsaga-tracker"
  strategy="afterInteractive"
  data-site-key="YOUR_SITE_KEY"
  src="https://clearsaga.com/js/script.js"
/>

<script
  is:inline
  defer
  data-site-key="YOUR_SITE_KEY"
  src="https://clearsaga.com/js/script.js"
></script>

export default defineNuxtConfig({
  app: {
    head: {
      script: [
        {
          defer: true,
          'data-site-key': 'YOUR_SITE_KEY',
          src: 'https://clearsaga.com/js/script.js',
        },
      ],
    },
  },
})

<script>
  (function () {
    var s = document.createElement('script')
    s.defer = true
    s.setAttribute('data-site-key', 'YOUR_SITE_KEY')
    s.src = 'https://clearsaga.com/js/script.js'
    document.head.appendChild(s)
  })()
</script>

The install guides have the steps for every platform.

Where it goes #

Put the tag inside the <head> of every page you want counted. On most sites that means one shared template or layout, not each page by hand. The defer attribute lets the page keep loading while the script is fetched, so the tag does not slow your site down.

You do not need extra code for a site that changes pages without a full reload, such as a single-page app. The script notices when the address changes and counts the new page.

The light and the full script #

There are two scripts. Both count visits, pages, custom events and missing pages in the same way.

The tag for the full script differs only in its src:

<script
  defer
  data-site-key="YOUR_SITE_KEY"
  src="https://clearsaga.com/js/script.full.js"
></script>

You rarely pick by hand. When web vitals, the cross-domain option or Remember returning visitors is switched on for a site, Settings, Installation prints the tag for the full script, and you replace the old tag with it.

What the script sends #

For each page view the script sends the path of the page and the hostname. With the first page view after a page loads it also sends the site the visitor came from, when that is a different site from yours. For a custom event it also sends the name of the event and the properties you gave it.

Every hit also carries your site key, the version of the script, and a mark when the browser is driven by automation, which is one of the signs used to leave bots out. The full script can add one more thing: when the revenue option is set on the tag by hand, every hit carries a random id made for that one page load, kept in memory only.

It is just as useful to know what it leaves alone:

• It sets no cookies and stores nothing in the browser that could recognise a visitor, unless Remember returning visitors is on for the site. That switch is off by default. On, the full script keeps one cookie for a visitor who agreed and sends its random id with each hit. The light script never does.
• It never sends the query string of a page. When campaign capture is switched on, it reads the UTM tags from the address and nothing else. With Match sales to ads on, the full script also reads the ad click IDs: see ad attribution.
• On a page view it sends the referring site only, never the page or its query string. When a visitor lands on a missing page, the 404 hit also carries the path of the page that linked there, so you can see where the broken link is. The query string is still left out. See 404 tracking.
• The only thing it reads from the browser's storage is clearsaga_ignore, the switch that lets you leave your own visits out. The cookie above is the one other thing, and only with the switch on.
• It sends nothing at all when the browser has Global Privacy Control or Do Not Track switched on.

Privacy: cookieless by default explains how a visitor is counted without any of that, and what the switch adds.

Good to know #

• There is no switch for local development: a page with a valid key sends visits from your own machine too. Use a separate site for testing.
• Use one tag per page. When the same key is on a page twice, only the first tag runs, so remove the old tag when you switch between the light and the full script.
• If your site sends a Content Security Policy, allow https://clearsaga.com in script-src and connect-src.
• The script has no version in its name and no integrity hash. Browsers check for a new copy on every page load, so updates reach your site at once.
• After you rotate the site key, the old tag stops recording within about a minute.
• Options you switch on here reach a page a moment after it starts loading. If the first page view must always carry them, for example campaign fields, put the attribute on the tag itself.

Check that it works #

Open your site in a normal browser window, then open the dashboard. The first visit shows up within a few seconds, and the status on Settings, Installation changes to "Receiving data". If nothing arrives, troubleshooting lists what to check, most likely cause first.

Next: Install guides, Script options, Troubleshooting