Analytics Script

SDK Reference

The easiest way to add analytics to your blog. Just add a single script tag - no build step, no configuration needed.

Add this script tag to your article pages:

article.html

<script
  src="https://cdn.simplist.blog/analytics.js"
  data-api-key="prj_your_api_key"
></script>

That's it! The script automatically tracks:

Page views
Time on page
Scroll depth (with milestones at 25%, 50%, 75%, 90%)
Bounce rate
Geographic location
Device and browser info
Referrer and UTM parameters

Property	Type	Description	Default
`data-api-key*`	string	Your Simplist API key (required)	-
`data-slug`	string	Article slug to track. Auto-detected from URL if not provided	-
`data-api-url`	string	Override API endpoint	https://api.simplist.blog/v1
`data-debug`	boolean	Enable debug logging in console	false

When data-slug is not provided, the script automatically extracts the slug from the URL path:

URL	Detected Slug
/blog/my-article	my-article
/articles/getting-started	getting-started
/posts/2024/hello-world	hello-world

Basic usage - auto-detect slug from URL:

<script
  src="https://cdn.simplist.blog/analytics.js"
  data-api-key="prj_abc123"
></script>

Explicit slug - when URL doesn't match article slug:

<script
  src="https://cdn.simplist.blog/analytics.js"
  data-api-key="prj_abc123"
  data-slug="my-custom-slug"
></script>

Debug mode - for troubleshooting:

<script
  src="https://cdn.simplist.blog/analytics.js"
  data-api-key="prj_abc123"
  data-debug="true"
></script>

The script tracks these metrics automatically:

Metric	Description
Page View	Recorded when the script loads
Time on Page	Calculated from page load to unload
Scroll Depth	Maximum scroll position reached (0-100%)
Exit Position	Scroll position when user leaves
Bounce	true if time < 10s AND scroll < 25%
Screen Size	Viewport width and height
Referrer	The page that linked to this one
UTM Parameters	utm_source, utm_medium, utm_campaign, etc.

The script automatically tracks when users reach these scroll positions:

25% - User started reading
50% - User is engaged
75% - User read most of the content
90% - User reached the end

These are stored as events and can be used to build engagement funnels.

The script fetches geographic data from the client side (via ipinfo.io):

Country and country code
Region/State
City
Timezone

The script exposes a global SimplistAnalytics object for custom tracking.

// Track a button click
SimplistAnalytics.track('button_click', {
  buttonId: 'cta-signup',
  buttonText: 'Sign Up Now'
})

// Track a video play
SimplistAnalytics.track('video_play', {
videoId: 'intro-video',
duration: 120
}, 45) // 45 = scroll position when event occurred

// Track a form submission
SimplistAnalytics.track('form_submit', {
formId: 'newsletter',
email: 'user@example.com'
})

Force send all pending events immediately:

// Send all pending data before navigation
SimplistAnalytics.flush()

app/blog/[slug]/page.tsx

import Script from 'next/script'

export default function ArticlePage({ params }: { params: { slug: string } }) {
return (
<>
<Script
        src="https://cdn.simplist.blog/analytics.js"
        data-api-key={process.env.NEXT_PUBLIC_SIMPLIST_API_KEY}
        data-slug={params.slug}
        strategy="afterInteractive"
      />
<article>
{/* Your article content */}
</article>
</>
)
}

src/pages/blog/[slug].astro

---
const { slug } = Astro.params
---

<html>
  <head>
    <script
      src="https://cdn.simplist.blog/analytics.js"
      data-api-key={import.meta.env.PUBLIC_SIMPLIST_API_KEY}
      data-slug={slug}
    />
  </head>
  <body>
    <article>
      <!-- Your article content -->
    </article>
  </body>
</html>

layouts/partials/analytics.html

{{ if .IsPage }}
<script
  src="https://cdn.simplist.blog/analytics.js"
  data-api-key="{{ .Site.Params.simplistApiKey }}"
  data-slug="{{ .File.BaseFileName }}"
></script>
{{ end }}

article.html

<!DOCTYPE html>
<html>
<head>
  <title>My Article</title>
</head>
<body>
  <article>
    <h1>My Article Title</h1>
    <p>Article content here...</p>
  </article>

  <!-- Add at the end of body -->
  <script
    src="https://cdn.simplist.blog/analytics.js"
    data-api-key="prj_your_api_key"
    data-slug="my-article"
  ></script>

</body>
</html>

Choose the right approach for your needs:

Feature	Script	SDK
Setup	One line of HTML	npm install + code
Auto-tracking	Yes (scroll, time, geo)	Manual implementation
Custom events	SimplistAnalytics.track()	client.analytics.track()
Server-side	No	Yes
Bundle size	~5KB (external)	~15KB (in your bundle)
Control	Limited	Full

Use the Script when:

You want zero-code analytics
You're using a static site generator
You don't need server-side tracking

Use the SDK when:

You need server-side tracking
You want full control over when/what to track
You're building a React/Next.js app with complex requirements

The script automatically detects and ignores bot traffic:

Search engine crawlers (Googlebot, Bingbot, etc.)
Social media bots (Facebook, Twitter, LinkedIn)
Monitoring tools (Pingdom, UptimeRobot)
Headless browsers (Puppeteer, Playwright)
Common HTTP clients (curl, wget, axios)

Bot visits are not counted in your analytics.

The analytics script is designed to be privacy-friendly:

No cookies - Uses localStorage for session persistence
Anonymous tracking - No personal data collected
IP anonymization - IPs are never stored
GDPR compliant - No consent banner needed
Adblocker-friendly - First-party domain, not blocked

Check the browser console for errors
Enable debug mode with data-debug="true"
Verify your API key is correct
Ensure the article slug exists in your project

If auto-detection fails, explicitly set the slug:

<script
  src="https://cdn.simplist.blog/analytics.js"
  data-api-key="prj_abc123"
  data-slug="your-article-slug"
></script>

The script uses navigator.sendBeacon() for reliable delivery on page unload. This works in all modern browsers. If you're using an older browser, events may be lost on fast navigation.

Quick Help

Yes, but be careful not to double-track. The script is best for client-side pages, while the SDK is for server-side or when you need more control. Don't use both on the same page.

The script tracks the initial page load. For SPAs with client-side routing, you'll need to manually call SimplistAnalytics.flush() before navigation and re-initialize tracking. Consider using the SDK for SPAs.

The script tracks one article per page. If you have a list of articles, only track the main article being viewed. For article previews or lists, don't include the analytics script.

Yes, the script loads asynchronously and won't block page rendering. It initializes after the DOM is ready.

Analytics SDK - Full SDK documentation
Analytics Examples - Complete integration examples
REST API: Track - Direct API access

Edit on GitHub

Tags API

SEO API

Quick Start

Configuration

Data Attributes

Auto-Detection

Examples

What Gets Tracked

Automatic Metrics

Scroll Milestones

Geographic Data

JavaScript API

Track Custom Events

Flush Events

Framework Integration

Next.js

Astro

Hugo

Plain HTML

Script vs SDK

Bot Detection

Privacy & GDPR

Troubleshooting

Script not tracking

Slug not detected

Events not sending on page leave

Frequently Asked Questions

Quick Help

See Also

Command Palette