@pressflow/tracker

Lightweight page view tracking for Pressflow blogs. Under 1 KB gzipped. Uses navigator.sendBeacon() with fetch keepalive fallback for reliable delivery.

Installation

Script tag (recommended)

Add this snippet to your article pages. No build step required.

<script
  src="https://cdn.pressflow.io/tracker/v1/snippet.js"
  data-api-url="https://api.pressflow.io"
  data-api-key="pk_..."
  data-article-id="article-uuid"
  defer
></script>

npm

npm install @pressflow/tracker

Quick Start

import { Tracker } from "@pressflow/tracker"

const tracker = new Tracker({
  baseUrl: "https://api.pressflow.io",
  apiKey: "pk_...",
  articleId: "article-uuid", // auto-tracks on construction
})

Or track manually:

const tracker = new Tracker({
  baseUrl: "https://api.pressflow.io",
  apiKey: "pk_...",
})

tracker.trackPageView("article-uuid")

API Reference

new Tracker(config)

Creates a tracker instance. If articleId is provided, a page view is tracked immediately.

trackPageView(articleId)

Sends a page view event for the given article. Each tracker instance only fires once — subsequent calls are ignored.

| Parameter | Type | Required | Description | | ----------- | -------- | -------- | ------------------------ | | articleId | string | Yes | The article's unique ID |

Configuration

TrackerConfig

| Parameter | Type | Required | Default | Description | | ----------- | -------- | -------- | ------- | ------------------------------ | | baseUrl | string | Yes | - | Pressflow API base URL | | apiKey | string | Yes | - | Your public API key | | articleId | string | No | - | Auto-track this article on init |

Script tag attributes

| Attribute | Required | Description | | ----------------- | -------- | ------------------------ | | data-api-url | Yes | Pressflow API base URL | | data-api-key | Yes | Your public API key | | data-article-id | Yes | The article's unique ID |

How it works

1. On construction (or when trackPageView is called), the tracker sends a single event containing the article ID, page referrer, and user agent.
2. It first attempts navigator.sendBeacon() for non-blocking delivery that survives page unloads.
3. If sendBeacon is unavailable or fails, it falls back to fetch with keepalive: true.
4. Each tracker instance tracks at most one page view to prevent duplicates.

GDPR

The tracker collects only the page referrer and user agent string — no cookies, no fingerprinting, no personal data. It is compatible with cookie-free analytics. If your site requires user consent for any analytics, gate the script or Tracker instantiation behind your consent mechanism.

License

MIT