Install Simple Analytics | OpsBlu Docs

Install Simple Analytics

Install the Simple Analytics tracking tag or SDK — step-by-step embed instructions, verification, and troubleshooting.

Installation

Simple Analytics is a privacy-friendly analytics platform that doesn't use cookies and respects user privacy. Installation is straightforward with multiple options for different frameworks and platforms.

Finding Your Installation Script

Before installing, ensure you have a Simple Analytics account:

  1. Sign up at simpleanalytics.com
  2. Add your website domain in the dashboard
  3. Your script will be automatically configured for your domain

Standard JavaScript Installation

The simplest method for most websites - add the script to your HTML.

Basic Script

Add this to your HTML <head> or before the closing </body> tag:

<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>

Custom Domain Setup

If you're using a custom domain for analytics (to bypass ad blockers):

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

Auto Events Tracking

Enable automatic event tracking for clicks, form submissions, and more:

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

NPM Package Installation

For modern JavaScript applications using build tools.

Installation

npm install simple-analytics-vue

Or for general JavaScript projects:

npm install sa-sdk-javascript

Basic Usage

import { loadScript } from 'sa-sdk-javascript';

// Load Simple Analytics
loadScript();

With Custom Configuration

import { loadScript } from 'sa-sdk-javascript';

loadScript({
  hostname: 'analytics.yourdomain.com',
  autoCollect: true,
  ignorePages: ['/admin']
});

React Integration

Using Hooks

import { useEffect } from 'react';

function App() {
  useEffect(() => {
    // Load Simple Analytics script
    const script = document.createElement('script');
    script.src = 'https://scripts.simpleanalyticscdn.com/latest.js';
    script.async = true;
    script.defer = true;
    document.body.appendChild(script);

    return () => {
      document.body.removeChild(script);
    };
  }, []);

  return <div>Your App</div>;
}

With React Router

Track page views on route changes:

import { useEffect } from 'react';
import { useLocation } from 'react-router-dom';

function App() {
  const location = useLocation();

  useEffect(() => {
    // Track page view on route change
    if (window.sa_event) {
      window.sa_event('pageview');
    }
  }, [location]);

  return <YourRoutes />;
}

React Component

import React, { useEffect } from 'react';

export function SimpleAnalytics() {
  useEffect(() => {
    // Load script
    const script = document.createElement('script');
    script.src = 'https://scripts.simpleanalyticscdn.com/latest.js';
    script.async = true;
    script.defer = true;
    document.head.appendChild(script);

    // Load auto-events
    const autoEvents = document.createElement('script');
    autoEvents.src = 'https://scripts.simpleanalyticscdn.com/auto-events.js';
    autoEvents.async = true;
    autoEvents.defer = true;
    document.head.appendChild(autoEvents);

    return () => {
      document.head.removeChild(script);
      document.head.removeChild(autoEvents);
    };
  }, []);

  return null;
}

Next.js Integration

App Router (_app.js)

// pages/_app.js
import Script from 'next/script';

function MyApp({ Component, pageProps }) {
  return (
    <>
      <Script
        src="https://scripts.simpleanalyticscdn.com/latest.js"
        strategy="afterInteractive"
      />
      <Component {...pageProps} />
    </>
  );
}

export default MyApp;

With Auto Events

// pages/_app.js
import Script from 'next/script';

function MyApp({ Component, pageProps }) {
  return (
    <>
      <Script
        src="https://scripts.simpleanalyticscdn.com/latest.js"
        strategy="afterInteractive"
      />
      <Script
        src="https://scripts.simpleanalyticscdn.com/auto-events.js"
        strategy="afterInteractive"
      />
      <Component {...pageProps} />
    </>
  );
}

export default MyApp;

Document (_document.js)

// pages/_document.js
import { Html, Head, Main, NextScript } from 'next/document';

export default function Document() {
  return (
    <Html>
      <Head>
        <script
          async
          defer
          src="https://scripts.simpleanalyticscdn.com/latest.js"
        />
        <noscript>
          <img
            src="https://queue.simpleanalyticscdn.com/noscript.gif"
            alt=""
            referrerPolicy="no-referrer-when-downgrade"
          />
        </noscript>
      </Head>
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  );
}

Vue Integration

Vue 3 Plugin

// plugins/simpleAnalytics.js
export default {
  install: (app) => {
    // Load Simple Analytics
    const script = document.createElement('script');
    script.src = 'https://scripts.simpleanalyticscdn.com/latest.js';
    script.async = true;
    script.defer = true;
    document.head.appendChild(script);

    // Add to global properties
    app.config.globalProperties.$sa = window.sa_event;
  }
};

// main.js
import { createApp } from 'vue';
import App from './App.vue';
import SimpleAnalytics from './plugins/simpleAnalytics';

const app = createApp(App);
app.use(SimpleAnalytics);
app.mount('#app');

Vue Component

<template>
  <div></div>
</template>

<script>
export default {
  name: 'SimpleAnalytics',
  mounted() {
    const script = document.createElement('script');
    script.src = 'https://scripts.simpleanalyticscdn.com/latest.js';
    script.async = true;
    script.defer = true;
    document.head.appendChild(script);
  }
};
</script>

Vue Router Integration

// router/index.js
import { createRouter, createWebHistory } from 'vue-router';

const router = createRouter({
  history: createWebHistory(),
  routes: [...]
});

// Track page views
router.afterEach((to) => {
  if (window.sa_event) {
    window.sa_event('pageview', { path: to.fullPath });
  }
});

export default router;

Angular Integration

Add to index.html

<!-- src/index.html -->
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Your App</title>
  <base href="/">
  <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>
</head>
<body>
  <app-root></app-root>
</body>
</html>

Angular Service

// services/analytics.service.ts
import { Injectable } from '@angular/core';
import { NavigationEnd, Router } from '@angular/router';
import { filter } from 'rxjs/operators';

declare global {
  interface Window {
    sa_event: any;
  }
}

@Injectable({
  providedIn: 'root'
})
export class AnalyticsService {
  constructor(private router: Router) {
    this.trackPageViews();
  }

  trackPageViews() {
    this.router.events
      .pipe(filter(event => event instanceof NavigationEnd))
      .subscribe((event: NavigationEnd) => {
        if (window.sa_event) {
          window.sa_event('pageview', { path: event.urlAfterRedirects });
        }
      });
  }

  trackEvent(eventName: string, metadata?: any) {
    if (window.sa_event) {
      window.sa_event(eventName, metadata);
    }
  }
}

WordPress Installation

Using Plugin

  1. Install "Insert Headers and Footers" plugin
  2. Go to Settings > Insert Headers and Footers
  3. Add to Scripts in Header:
<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>

Manual Theme Integration

Edit header.php in your theme:

<!-- Add before closing </head> tag -->
<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>

WordPress Multisite

Add to wp-config.php or use a plugin that works network-wide.

Shopify Integration

Theme Installation

  1. Go to Online Store > Themes
  2. Click Actions > Edit code
  3. Open theme.liquid
  4. Add before </head>:
<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>

Google Tag Manager Installation

Create Custom HTML Tag

  1. Create a new Tag in GTM
  2. Choose "Custom HTML" tag type
  3. Add the script:
<script async defer src="https://scripts.simpleanalyticscdn.com/latest.js"></script>
  1. Set trigger to "All Pages"
  2. Publish the container

Ghost CMS Integration

Code Injection

  1. Go to Settings > Code injection
  2. Add to Site Header:
<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>

Webflow Integration

Custom Code

  1. Go to Project Settings > Custom Code
  2. Add to Head Code:
<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>

Content Security Policy

If you use CSP headers, add these directives:

Content-Security-Policy:
  script-src https://scripts.simpleanalyticscdn.com;
  img-src https://queue.simpleanalyticscdn.com;
  connect-src https://queue.simpleanalyticscdn.com;

For custom domains:

Content-Security-Policy:
  script-src https://analytics.yourdomain.com;
  img-src https://analytics.yourdomain.com;
  connect-src https://analytics.yourdomain.com;

Ignoring Pages

Exclude specific pages from tracking:

<script>
  window.sa_pageview_ignore = ['/admin', '/dashboard', '/settings'];
</script>
<script async defer src="https://scripts.simpleanalyticscdn.com/latest.js"></script>

Testing Installation

Browser Console Check

// Check if Simple Analytics loaded
console.log(window.sa_event);

// Should output a function if loaded correctly

Network Tab

  1. Open browser DevTools
  2. Go to Network tab
  3. Filter for "simpleanalytics"
  4. Look for requests to scripts.simpleanalyticscdn.com and queue.simpleanalyticscdn.com

Dashboard Verification

  1. Visit your website
  2. Wait 1-2 minutes
  3. Check Simple Analytics dashboard
  4. Look for real-time visitor count

Troubleshooting

Script Not Loading

Check ad blockers: Some ad blockers block analytics scripts

  • Solution: Use a custom domain for tracking

Check CSP headers: Content Security Policy might block the script

  • Solution: Add Simple Analytics domains to CSP

Check console errors: Look for JavaScript errors

  • Solution: Ensure script URL is correct

No Data in Dashboard

Domain mismatch: Ensure your website domain matches dashboard settings

  • Solution: Verify domain in Simple Analytics settings

Script blocked: Check if script is being blocked by browser extensions

  • Solution: Test in incognito mode

Localhost testing: Simple Analytics doesn't track localhost by default

  • Solution: Add localhost exception in settings

Additional Resources

Back to top