CAnalytics - AI Agent Technical Reference

This document is designed to be consumed by AI coding assistants. It provides complete technical specifications for integrating CAnalytics into web projects.

Purpose

CAnalytics is a privacy-first web analytics service. It tracks pageviews, custom events, and JavaScript errors without cookies, personal data collection, or GDPR consent requirements.

Script Location

https://analytics.cloudlineconsulting.com/ctag.js

Installation

Add the following script tag inside the <head> element. The user must replace C-YOUR_API_KEY with their actual API key obtained from the CAnalytics dashboard.

<script
  src="https://analytics.cloudlineconsulting.com/ctag.js"
  data-key="C-YOUR_API_KEY"
  async
></script>

Configuration Attributes

All configuration is done via data attributes on the script tag.

Attribute	Required	Default	Description
`data-key`	Yes	—	CTag API key. Format: `C-` followed by 20 lowercase alphanumeric characters (total 22 characters).
`data-auto`	No	`"true"`	When `"true"`: tracks initial pageview on load + all SPA navigation (pushState, replaceState, popstate). Set to `"false"` to disable all automatic tracking.
`data-errors`	No	`"true"`	When `"true"`: captures uncaught JavaScript errors and unhandled promise rejections. Set to `"false"` to disable.
`data-userid`	No	—	Custom user ID to associate with events. When set, replaces the auto-generated anonymous ID (`anon-*`). Use for logged-in users.

Automatic Behavior

When data-auto="true" (default)

Tracks a pageview event immediately when script initializes.
Patches history.pushState and history.replaceState to track pageviews on each call.
Listens to popstate event to track browser back/forward navigation.

This covers all single-page application (SPA) frameworks without additional configuration.

When data-auto="false"

No automatic pageview tracking occurs. Use window.ctag.pageview() and window.ctag.track() manually.

When data-errors="true" (default)

Listens to window.error event for uncaught exceptions.
Listens to unhandledrejection event for promise rejections.
Sends an event with type "error" containing message, filename, line number, column number, and stack trace (truncated to 1000 characters).

JavaScript API

The script exposes a global window.ctag object with two methods:

window.ctag.pageview()

Manually track a pageview. Use when data-auto="false" or for custom navigation scenarios.

window.ctag.pageview();

window.ctag.identify(userId)

Associate events with a known user. Call after user login. Replaces the anonymous ID with the provided user ID for all subsequent events. Also persists to localStorage.

// After user authenticates
window.ctag.identify('user_12345');

// All subsequent events will use 'user_12345' as userId instead of 'anon-*'

Alternative: Set data-userid="user_12345" on the script tag if the user ID is known at page load.

window.ctag.track(eventType, properties?)

Track a custom event with optional properties object.

// Event without properties
window.ctag.track('signup');

// Event with properties
window.ctag.track('purchase', {
  orderId: 'ORD-12345',
  total: 99.99,
  currency: 'USD'
});

// Button click tracking
window.ctag.track('click', { button: 'cta_header', location: 'homepage' });

// Form submission
window.ctag.track('form_submit', { form: 'contact', success: true });

TypeScript Declaration

For TypeScript projects, add this declaration:

declare global {
  interface Window {
    ctag: {
      track: (eventType: string, props?: Record<string, unknown>) => void;
      pageview: () => void;
      identify: (userId: string) => void;
    };
  }
}

Data Collected Per Event

Every event (pageview, custom, error) automatically includes:

Field	Type	Description
`type`	string	Event type: `"pageview"`, `"error"`, or custom event name
`url`	string	Full URL including protocol, domain, path, and query string
`path`	string	URL pathname only (e.g., `/products/123`)
`domain`	string	Hostname extracted from URL
`referrer`	string	Document referrer (previous page URL)
`sessionId`	string	16-character session identifier. Stored in localStorage. Expires after 30 minutes of inactivity.
`userId`	string	Anonymous visitor ID prefixed with `anon-`. Stored in localStorage. Persists for 1 year.
`timestamp`	string	ISO 8601 format (e.g., `2026-02-02T15:30:00.000Z`)
`isLocal`	boolean	`true` if hostname is localhost, 127.0.0.1, .localhost, .local, or file:// protocol
`queryParams`	object	All URL query parameters as key-value pairs. Includes UTM tags.
`custom`	object	Custom properties passed to `track()`. Omitted if empty.

Framework Integration Examples

Plain HTML

<!DOCTYPE html>
<html>
<head>
  <script
    src="https://analytics.cloudlineconsulting.com/ctag.js"
    data-key="C-YOUR_API_KEY"
    async
  ></script>
</head>
<body>
  <button onclick="ctag.track('click', { button: 'demo' })">Track Click</button>
</body>
</html>

Next.js (App Router)

File: app/layout.tsx

import Script from 'next/script';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <head>
        <Script
          src="https://analytics.cloudlineconsulting.com/ctag.js"
          data-key="C-YOUR_API_KEY"
          strategy="afterInteractive"
        />
      </head>
      <body>{children}</body>
    </html>
  );
}

Next.js (Pages Router)

File: pages/_app.tsx

import Script from 'next/script';
import type { AppProps } from 'next/app';

export default function App({ Component, pageProps }: AppProps) {
  return (
    <>
      <Script
        src="https://analytics.cloudlineconsulting.com/ctag.js"
        data-key="C-YOUR_API_KEY"
        strategy="afterInteractive"
      />
      <Component {...pageProps} />
    </>
  );
}

React (Vite / Create React App)

File: index.html

<!DOCTYPE html>
<html>
<head>
  <script
    src="https://analytics.cloudlineconsulting.com/ctag.js"
    data-key="C-YOUR_API_KEY"
    async
  ></script>
</head>
<body>
  <div id="root"></div>
  <script type="module" src="/src/main.tsx"></script>
</body>
</html>

Vue 3

File: index.html

<!DOCTYPE html>
<html>
<head>
  <script
    src="https://analytics.cloudlineconsulting.com/ctag.js"
    data-key="C-YOUR_API_KEY"
    async
  ></script>
</head>
<body>
  <div id="app"></div>
  <script type="module" src="/src/main.ts"></script>
</body>
</html>

Astro

In layout component:

<script
  src="https://analytics.cloudlineconsulting.com/ctag.js"
  data-key="C-YOUR_API_KEY"
  async
  is:inline
></script>

Svelte / SvelteKit

File: src/app.html

<!DOCTYPE html>
<html>
<head>
  <script
    src="https://analytics.cloudlineconsulting.com/ctag.js"
    data-key="C-YOUR_API_KEY"
    async
  ></script>
  %sveltekit.head%
</head>
<body>
  <div>%sveltekit.body%</div>
</body>
</html>

Custom Events Only Mode

To disable all automatic tracking and use only manual track() calls:

<script
  src="https://analytics.cloudlineconsulting.com/ctag.js"
  data-key="C-YOUR_API_KEY"
  data-auto="false"
  async
></script>

Then call manually:

// Track pageview when ready
window.ctag.pageview();

// Track custom events
window.ctag.track('user_action', { action: 'specific' });

Disabling Error Tracking

<script
  src="https://analytics.cloudlineconsulting.com/ctag.js"
  data-key="C-YOUR_API_KEY"
  data-errors="false"
  async
></script>

Error Event Structure

When an error is captured, the custom field contains:

Field	Description
`message`	Error message string
`filename`	Source file URL where error occurred
`lineno`	Line number
`colno`	Column number
`stack`	Stack trace (max 1000 characters)
`type`	`"unhandledrejection"` for promise rejections, absent for regular errors

Technical Implementation Details

Network Request

Method: POST
Endpoint: {script_origin}/api/collect (derived from script src attribute)
Headers: Content-Type: application/json, x-api-key: {data-key value}
Body: JSON-encoded event object
Uses fetch() with keepalive: true to survive page unloads

Storage

ctag_sid: Session ID in localStorage
ctag_sts: Session timestamp in localStorage (for 30-minute inactivity timeout)
ctag_uid: Visitor ID in localStorage

ID Generation

16-character alphanumeric string generated using crypto.getRandomValues().

Failure Behavior

All errors are silently caught. The script never throws exceptions or breaks page functionality.

Privacy Compliance

No cookies used
No IP addresses stored server-side
No browser fingerprinting
No cross-site tracking
No third-party data sharing
GDPR compliant by design
CCPA compliant
No consent banner required

Domain Whitelisting

The API key is bound to allowed domains configured in the CAnalytics dashboard. Requests from non-whitelisted domains receive HTTP 403 Forbidden. The user must add their domain(s) to the CTag configuration.

Common domains to add:

example.com and www.example.com for production
staging.example.com for staging
localhost for local development

User Setup Prerequisites

Before integration, the user must:

Create an account at the CAnalytics dashboard
Create or join an organization
Create a CTag with allowed domains
Copy the API key (format: C- followed by 20 lowercase alphanumeric characters)

Dashboard URL: https://analytics.cloudlineconsulting.com/