simpledata
← Documentation

Manual Installation Guide

Install SimpleData on any website using JavaScript

This guide covers how to install SimpleData Analytics on any website using the JavaScript tracker. This works for custom websites, static sites, or platforms not covered by our plugins.

Step 1: Get Your Site ID

  1. Log in to SimpleData Dashboard
  2. Go to Sites and create a new site
  3. Select the appropriate Site Type (Web or Ecommerce)
  4. Copy your Site ID

Step 2: Install the Tracker Script

Add this code to your website's <head> section, just before the closing </head> tag. Replace YOUR_SITE_ID with the ID you copied in Step 1:

<!-- SimpleData Analytics -->
<script async src="https://api.simpledata.dev/t.js"
  data-site-id="YOUR_SITE_ID"></script>

✅ Done! Pageview tracking is now active. The tracker will automatically track all page visits, outbound link clicks, file downloads and 404 pages, and, when a page is left, how far down it was scrolled and how long it was on screen.

Step 3: Track Ecommerce Events (Optional)

If you're running an ecommerce site, you can track purchases and cart events.

Track Purchases

Add this code to your order confirmation page (thank you page):

<script>
  if (window.simpleAnalytics) {
    window.simpleAnalytics.trackPurchase({
      revenue: 129.99,
      currency: 'USD',
      orderId: 'ORDER-12345',
      products: [
        {
          id: 'PROD-1',
          name: 'T-Shirt',
          quantity: 2,
          price: 64.99
        }
      ]
    });
  }
</script>

Track Add to Cart

Add this to your "Add to Cart" button:

<button onclick="
  window.simpleAnalytics && window.simpleAnalytics.trackAddToCart({
    productId: 'PROD-1',
    productName: 'T-Shirt',
    quantity: 1,
    price: 64.99
  })
">
  Add to Cart
</button>

Step 4: Track Custom Events (Optional)

You can track any custom event using the track() method:

window.simpleAnalytics.track('button_click', {
  button_name: 'Sign Up',
  page: 'Homepage'
});

window.simpleAnalytics.track('video_play', {
  video_title: 'Product Demo',
  duration: 120
});

No JavaScript needed for clicks and forms: add data-sd-goal="signup_click" to a button, link or form, and data-sd-goal-* attributes for properties. A form counts when it is submitted. See Goals for details. /docs/goals

Step 5: Verify Installation

  1. Visit your website in a new incognito/private window
  2. Navigate to a few pages
  3. Go to your SimpleData Dashboard
  4. Check if pageviews are appearing (may take 1-2 minutes)

Debug Mode

Open your browser's DevTools (F12) and check the Network tab for requests to api.simpledata.dev/api/v1/events. Each event is a POST sent as text/plain (with a JSON body) and should get a 202 Accepted response. There is no OPTIONS request before it; that is expected. Leaving a page (or switching to another tab) sends one more POST, to /api/v1/events/engagement, with its scroll depth and time on page.

Advanced Configuration

Single Page Applications (SPA)

The tracker automatically detects URL changes in SPAs (React, Vue, Angular) via history.pushState and popstate events. No additional configuration needed.

Content Security Policy (CSP)

If you use CSP headers, add these directives:

script-src 'self' https://api.simpledata.dev;
connect-src 'self' https://api.simpledata.dev;

Hosting the tracker yourself?

Load the script from api.simpledata.dev. A copy uploaded to your own server does not work: the script sends events to the domain it was loaded from, so they would go to your server instead of SimpleData.

  1. Keep the script tag pointing at https://api.simpledata.dev/t.js
  2. If a Content Security Policy blocks it, allow api.simpledata.dev as shown above

📝 The hosted script is updated with every release, so you get fixes without touching your site.

API Reference

trackPurchase(options)

Track an ecommerce purchase.

trackAddToCart(options)

Track when a user adds a product to cart.

track(eventName, properties)

Track a custom event.

data-sd-goal="name" and data-sd-goal-*

HTML attributes that send a custom event on click (or on submit, for forms), with up to 20 properties.

Troubleshooting

Pageviews not showing

  • •Check domain: Ensure your website domain matches the domain in SimpleData
  • •Check browser console: Look for JavaScript errors
  • •Ad blockers: Some ad blockers may block analytics scripts
  • •CORS: Ensure your site allows requests to api.simpledata.dev

Events not tracking

  • •Tracker loaded: Check that window.simpleAnalytics exists
  • •Syntax errors: Verify your JavaScript syntax
  • •Timing: Ensure tracker loads before calling tracking methods

Next Steps