Simple Analytics Events, API, and Setup

Install Simple Analytics' cookieless tracker, send events with sa_event(), bypass ad blockers via custom domains, and query the data export API.

How Simple Analytics Works

Simple Analytics collects website data through a lightweight JavaScript file (latest.js, under 3KB) that sends requests to Simple Analytics' servers on each pageview and custom event. The tracker does not set cookies, use localStorage, use fingerprinting, or store IP addresses.

Visitor uniqueness is determined at the server level using a hash of the IP address and User-Agent, combined with a daily rotating salt. The raw IP is discarded immediately after hashing. Because the salt rotates, Simple Analytics cannot identify returning visitors across days. There are no visitor profiles, session IDs, or cross-site tracking capabilities.

The data model consists of:

Pageviews -- URL path, referrer, viewport size, UTM parameters, country (derived from IP, then IP discarded), and timestamp
Events -- Named actions with optional metadata, tied to a page context
Goals -- Conversion rules defined in the dashboard, triggered by pageview paths or event names

All data is stored on EU-based infrastructure (Amsterdam). Simple Analytics is a managed SaaS service with no self-hosted option.

Installing the Tracking Script

Add the script to the <head> or before </body> on every page:

<script async defer src="https://scripts.simpleanalyticscdn.com/latest.js"></script>
<noscript>
  <img src="https://queue.simpleanalyticscdn.com/noscript.gif"
       alt="" referrerpolicy="no-referrer-when-downgrade" />
</noscript>

The <noscript> image tag tracks visitors who have JavaScript disabled. Simple Analytics automatically detects the domain from window.location.hostname -- no site ID or configuration attribute is needed.

Script Attributes

Attribute	Description
`data-hostname`	Override the tracked hostname (for staging/proxies)
`data-collect-dnt`	Set to `true` to track visitors with Do Not Track enabled
`data-auto-collect`	Set to `false` to disable automatic pageview tracking
`data-sa-global`	Custom name for the global object (default: `sa_event`)
`data-ignore-pages`	Comma-separated URL paths to exclude from tracking

SPA Support

Simple Analytics automatically detects pushState and replaceState calls. For React Router, Next.js, Vue Router, and other History API-based frameworks, pageviews are tracked on each route change without additional configuration.

For hash-based routing, Simple Analytics listens for hashchange events automatically.

Custom Global Object Name

If sa_event conflicts with another library:

<script async defer src="https://scripts.simpleanalyticscdn.com/latest.js"
  data-sa-global="myTracker"></script>

<script>
  // Use custom name
  myTracker('button_click');
</script>

Event Tracking with sa_event()

Simple Analytics exposes a global sa_event() function for custom events:

// Basic event
sa_event('signup_click');

// Event with a callback
sa_event('form_submit', function() {
  console.log('Event sent');
});

// Event with metadata (passed as an object)
sa_event('purchase', { plan: 'pro', value: 49 });

Event Naming Rules

Event names are case-insensitive and normalized to lowercase
Spaces are converted to underscores
Special characters are stripped
Maximum length: 200 characters
sa_event('Sign Up') and sa_event('sign_up') are treated as the same event

Automated Events

Simple Analytics can automatically track certain actions without custom code:

Outbound link clicks:

<script async defer src="https://scripts.simpleanalyticscdn.com/auto-events.js"></script>

This script automatically sends events when visitors click external links, download files, or click email/phone links.

Download tracking patterns: Files with extensions .pdf, .csv, .docx, .xlsx, .zip, .dmg, .exe are tracked automatically when auto-events is enabled.

No-Code Event Tracking

Track events via HTML classes and data attributes:

<!-- Track click as event "cta_click" -->
<a href="/signup" class="sa-event-cta_click">Sign Up</a>

<!-- Using data attributes -->
<button data-sa-event="download_whitepaper">Download</button>

Collecting Events Server-Side

Send events from your backend without the JavaScript tracker:

curl -X POST https://queue.simpleanalyticscdn.com/events \
  -H "Content-Type: application/json" \
  -d '{
    "type": "event",
    "hostname": "example.com",
    "event": "server_purchase",
    "ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)...",
    "path": "/checkout/complete"
  }'

The ua (User-Agent) field is used for device and browser classification.

Bypassing Ad Blockers with Custom Domains

Ad blockers commonly block requests to simpleanalyticscdn.com. Serve the script from your own domain to avoid this.

CNAME Setup

Add a DNS record:

sa.example.com  CNAME  external.simpleanalyticscdn.com

Simple Analytics automatically provisions TLS for your subdomain.

Updated Script Tag

<script async defer src="https://sa.example.com/latest.js"></script>
<noscript>
  <img src="https://sa.example.com/noscript.gif"
       alt="" referrerpolicy="no-referrer-when-downgrade" />
</noscript>

The script detects the serving domain and sends all tracking requests to the same domain, making analytics traffic indistinguishable from first-party requests.

Proxy Alternative (Cloudflare Worker)

If you cannot create a CNAME (e.g., apex domain restrictions):

export default {
  async fetch(request) {
    const url = new URL(request.url);
    if (url.pathname === '/sa/latest.js') {
      return fetch('https://scripts.simpleanalyticscdn.com/latest.js');
    }
    if (url.pathname.startsWith('/sa/')) {
      const target = new URL(request.url);
      target.hostname = 'queue.simpleanalyticscdn.com';
      target.pathname = url.pathname.replace('/sa/', '/');
      return fetch(target, { method: request.method, headers: request.headers, body: request.body });
    }
    return new Response('Not found', { status: 404 });
  }
};

Then load from:

<script async defer src="https://example.com/sa/latest.js"></script>

Goals and Conversions

Goals are configured in the Simple Analytics dashboard and trigger on pageview paths or event names.

Pageview Goals

Define a URL pattern that counts as a conversion:

Exact match: /thank-you
Contains: checkout
Starts with: /blog/

When a visitor views a page matching the pattern, the goal is counted.

Event Goals

Link a goal to a custom event name. When sa_event('purchase') fires and a goal is configured for the purchase event, the conversion is recorded.

Goal Attribution

Simple Analytics attributes goal conversions to the referrer source of the visit. This enables basic conversion attribution: which traffic sources drive the most conversions.

API and Data Export

Simple Analytics provides a read-only API for retrieving pageview and event data.

Authentication

API requests use an API key passed as a query parameter or header:

curl "https://simpleanalytics.com/example.com.json?\
version=5&\
fields=histogram,pages&\
start=2025-01-01&\
end=2025-01-31&\
info=false" \
  -H "Api-Key: sa_api_key_XXXXX"

Pageview Data

# Aggregate stats for a date range
curl "https://simpleanalytics.com/example.com.json?\
version=5&\
fields=pageviews,visitors,pages&\
start=2025-01-01&\
end=2025-01-31" \
  -H "Api-Key: sa_api_key_XXXXX"

Response structure:

{
  "pageviews": 45230,
  "visitors": 12543,
  "pages": [
    { "value": "/", "pageviews": 8200, "visitors": 5100 },
    { "value": "/pricing", "pageviews": 3400, "visitors": 2800 },
    { "value": "/blog/analytics-guide", "pageviews": 2100, "visitors": 1900 }
  ]
}

Available Fields

pageviews, visitors, histogram (time series), pages, referrers, utm_sources, utm_mediums, utm_campaigns, utm_contents, utm_terms, browser_names, browser_versions, os_names, os_versions, device_types, screen_sizes, country_codes, language_codes.

Event Data

# Get custom events
curl "https://simpleanalytics.com/example.com/events.json?\
version=1&\
start=2025-01-01&\
end=2025-01-31" \
  -H "Api-Key: sa_api_key_XXXXX"

Histogram (Time Series)

curl "https://simpleanalytics.com/example.com.json?\
version=5&\
fields=histogram&\
start=2025-01-01&\
end=2025-01-31" \
  -H "Api-Key: sa_api_key_XXXXX"

Returns daily pageview and visitor counts for the date range.

CSV Export

Export all data as CSV by changing the extension:

curl "https://simpleanalytics.com/example.com.csv?\
version=5&\
fields=pages&\
start=2025-01-01&\
end=2025-01-31" \
  -H "Api-Key: sa_api_key_XXXXX" \
  -o export.csv

Filtering

Apply filters to API requests:

# Only mobile visitors
&filter_device_type=mobile

# Specific referrer
&filter_referrer=google.com

# Specific page
&filter_path=/pricing

Webhooks

Simple Analytics can send real-time notifications for events:

POST https://your-server.com/webhook
Content-Type: application/json

{
  "event": "purchase",
  "hostname": "example.com",
  "path": "/checkout",
  "created_at": "2025-01-15T10:30:00Z"
}

Configure webhooks in the Simple Analytics dashboard under Settings > Webhooks.

Common Issues

Script blocked by ad blockers: Set up a custom domain via CNAME to external.simpleanalyticscdn.com. This makes all tracking requests first-party and bypasses ad blockers.

Events not showing in dashboard: Events take up to 5 seconds to appear. Check that sa_event is defined (script must be loaded first). If using a custom global name via data-sa-global, call that name instead of sa_event.

SPA route changes double-counted: If using a framework that triggers both pushState and a custom tracking call, disable auto-collection with data-auto-collect="false" and track manually:

// Manual pageview on route change
router.afterEach(() => {
  sa_pageview(window.location.pathname);
});

Visitor counts differ from other tools: Simple Analytics does not count bots, crawlers, or prefetch requests. It does not set cookies, so the same visitor on two different days counts twice. Cross-tool comparisons will always show discrepancies.

Custom domain not working: Verify the CNAME record resolves correctly: dig sa.example.com CNAME. TLS certificate provisioning can take up to 30 minutes after DNS propagation. Ensure no conflicting A/AAAA records exist for the subdomain.

Noscript image not loading: The noscript pixel requires the referrerpolicy="no-referrer-when-downgrade" attribute. Without it, some browsers strip the referrer header and Simple Analytics cannot attribute the page.

Platform-Specific Considerations

GDPR-by-Default Architecture: Simple Analytics does not require GDPR consent banners because it does not process personal data as defined by the regulation. IP addresses are used transiently for geolocation and hashing, then discarded. No cookies means no ePrivacy directive consent requirement. This has been validated by multiple EU Data Protection Authorities.

Data Retention: All data is retained indefinitely. There is no automatic deletion or expiration. You can request complete account data deletion at any time.

Public Dashboards: Simple Analytics supports public dashboards that are accessible without authentication. Enable in site settings. The public URL follows the pattern:

https://simpleanalytics.com/example.com

This is commonly used by open-source projects and transparency-focused organizations to share traffic data publicly.

Tweet/Social Embed Tracking: Simple Analytics can track interactions with embedded tweets and social media elements. This is an automated feature when auto-events.js is included.

Multi-Domain Tracking: Track multiple domains under a single Simple Analytics site by setting data-hostname on each domain:

<!-- On app.example.com -->
<script async defer src="https://sa.example.com/latest.js"
  data-hostname="example.com"></script>

All pageviews are attributed to example.com regardless of which subdomain they originate from.

Email Reports: Simple Analytics sends automated email summaries on a weekly or monthly schedule. Configure recipients in the dashboard. Reports include pageviews, top pages, top referrers, and goal conversions.

Integration with Build Tools: Simple Analytics provides npm packages for framework integration:

npm install simple-analytics-vue  # Vue plugin
npm install @simpleanalytics/next  # Next.js plugin

These handle SPA tracking and provide typed event functions within framework components.

शीर्ष पर वापस जाएँ