A cutover checklist for moving Simple Analytics history

1. Pre-cutover audit and domain setup

Start with an inventory of your tracking tags, hostname overrides, event calls and reporting integrations. Register the destination site at clicktag.app and use the installation snippet from its settings. Include both data-hostname and the site-specific data-verify token so ownership verification can complete.

Check hostname boundaries before importing. example.com and www.example.com are distinct registrations unless you deliberately configure collection to use the same hostname. Use the site documentation to verify the intended setup.

If your site has a Content Security Policy, merge the new origins into it rather than replacing unrelated rules. Allow the host serving your snippet in script-src; allow the collector origin in img-src and connect-src. For the snippet below, all three use https://clicktag.io. A separate script-src-elem directive may also need updating.

2. Swap tracking tags and browser globals

Replace the legacy script references with the Clicktag collection bundle. Clicktag provides a drop-in script tag along with a verified image fallback for environments without JavaScript.

Core script replacement

Update your base layout templates with the modern tracker snippet. The data-verify attribute accepts your site verification token generated during registration:

<script
  async
  data-hostname="example.com"
  data-verify="your_verification_token"
  src="https://clicktag.io/latest.js"
></script>
<noscript>
  <img
    src="https://clicktag.io/noscript.gif?hostname=example.com"
    alt=""
    referrerpolicy="no-referrer-when-downgrade"
  />
</noscript>

The noscript pixel serves as a fallback for browsers that block JavaScript execution. It dispatches a minimal pageview hit directly to the collection backend without capturing client-side session metadata.

Transition globals and preload queues

Clicktag transitions the client namespace from sa_ to tt_. Any configuration options previously declared on window.sa_settings must now be assigned to window.tt_settings before the tracking script executes.

If your application logs custom events during the earliest stages of page initialization, replace the legacy pre-initialization queue with window.tt_event:

<script>
  window.tt_event =
    window.tt_event ||
    function () {
      window.tt_event.q.push(Array.from(arguments));
    };
  window.tt_event.q = window.tt_event.q || [];
</script>

Clicktag does not inspect or drain an existing sa_event array. If your application maintains dual tagging during a gradual rollout, run both queues in parallel. Each tracking library operates exclusively against its designated array.

3. Handle events, automated helpers, and SPAs

Audit all programmatic event calls across your UI against the browser event tracking documentation.

Custom event invocations

Update direct tracking calls to invoke window.tt_event:

if (typeof window.tt_event === "function") {
  window.tt_event("plan_selected", { plan: "standard" });
}

Event names are capped at 256 characters. Characters outside alphanumeric sets are converted into underscores, and leading or trailing underscores are automatically trimmed. Serialized metadata objects must remain within 4,096 characters.

Remove automated event scripts

Clicktag does not serve legacy helper files like /auto-events.js or /auto.js. Re-pointing those script sources to Clicktag hosts will break client logging because those legacy files attempt to dispatch to Simple Analytics globals. Replace automated click, external link, or download listeners with explicit window.tt_event calls inside your interface code.

Single-page navigation

Clicktag tracks history state transitions by listening to history.pushState and popstate events. Single-page applications running hash-based routing should add data-mode="hash" to the script tag. If your router handles navigations manually with data-auto-collect="false", call window.tt_pageview() explicitly on route transitions.

4. Execute the historical data import

Choose a UTC cutover boundary before starting the import. Import dates are inclusive: if live Clicktag tracking starts at midnight UTC on October 6, end the historical range on October 5. These are illustrative dates, not a required schedule. A clean day boundary avoids intentionally overlapping history with live collection.

Open the site's Integrations settings and supply the Simple Analytics credentials and source hostname. Review the selected start and end dates before queuing the job. Each job can cover up to 1,826 days, and only one job can be active for a site at a time. The account limit is 20 new import jobs per rolling 24 hours.

Monitor status rather than treating rows_imported as a visitor total. That counter includes records from checkpointed chunks sent to storage, including records already present and duration/scroll append rows. It is neither a unique-pageview count nor proof of exact stored totals.

Check the import reference for progress fields and retry controls. Imported pageviews use their source uniqueness flags; imported events have no visitor hash and do not add event visitors. Historical imports do not restore custom-event metadata or browser identities for funnels.

Migration verification matrix

Use this operational matrix to confirm each step of your tracking transition:

Post-cutover validation

Confirm live ingestion by navigating your site with developer tools active. A standard pageview triggers a GET request to /simple.gif containing type=pageview and your target hostname. When a user changes pages or closes their tab, duration and scroll statistics are sent to /append using navigator.sendBeacon.

Next, verify entries in your dashboard. Newly recorded views and events should appear under their corresponding paths within seconds. Note that automated scrapers and browsers with active Do Not Track headers are filtered out and will not appear in production tables.

If you have automated reporting jobs previously targeting Simple Analytics endpoints, migrate those routines to Clicktag. Update parameter schemes from start and end date strings to Unix-second from and to timestamps, and pass Clicktag API tokens in your authorization headers.

Frequently asked questions

Why do imported event counts show zero visitors in event breakdowns?

Event visitor metrics require distinct visitor hashes generated during real-time tracking. Because historical Simple Analytics export files do not provide visitor hashes, imported events populate total event volume but register zero unique visitors in breakdown views. Historical pageviews, by contrast, accurately record visitor counts using the source platform's exported is_unique flags.

Can I backfill missing historical dates using the live collection endpoint?

No. The Clicktag collection endpoint assigns timestamps upon server arrival and ignores any incoming timestamp or ts request parameters. Submitting past logs directly to the live collector will mark those entries with the current server time, corrupting your current time-series data. Historical data must be processed via the Imports API.

What happens if an import job fails mid-run?

Imports execute in checkpointed monthly chunks, processing pageviews followed by events. If a job fails or is canceled, completed chunks remain safely stored. Triggering a retry resumes processing from the last uncompleted chunk rather than starting over. The temporary API credentials are held for 7 days on failed jobs to permit retries without re-entering credentials.

Does Clicktag strip www from registered domains?

No. Clicktag normalizes hostnames to lowercase but leaves www subdomains intact. If your site answers traffic on both www.example.com and example.com, add your primary bare domain to your account and specify data-hostname="example.com" inside the tracker tag on all pages.