PastelTrack — Documentation

Getting Started

Quick Start

Get PastelTrack running on your site in 30 seconds. Just paste one script tag — no account needed.

1

Paste the widget script

Add this before the closing </body> tag on every page you want to track.

HTML

<script
  src="https://pasteltrack.minidu.lk/widget.js"
  data-id="yoursite.com"></script>

2

The widget appears automatically

A live counter badge renders on your page. It refreshes every 5 seconds. No configuration needed.

3

View your analytics dashboard

Visit pasteltrack.minidu.lk/user?id=yoursite.com to see detailed stats — no login required for the public view.

First visit auto-registers your site. The very first time a visitor hits your page with the widget, PastelTrack automatically creates a record for your domain. Nothing to configure.

How It Works

PastelTrack uses a lightweight session-based model to count unique visitors without storing any personal data permanently.

Session deduplication

Each visitor is fingerprinted using a one-way SHA-256 hash of their IP address and user agent. If the same fingerprint is seen within a 30-minute window, it counts as the same session — no double-counting. Sessions expire automatically.

Online count

The "online now" number reflects visitors who sent a ping within the last 5 minutes. The widget polls every 5 seconds, so this number is always fresh.

Bot filtering

Common bots, crawlers, and headless clients (Googlebot, curl, Python, Discord link previews, etc.) are detected and silently ignored.

PastelTrack counts page visits, not unique users across days. If the same person comes back 3 hours later, that's a new session and a new count. This is intentional — it reflects real engagement.

Widget

Embed Code

The full widget script with all available attributes:

HTML

<script
  src="https://pasteltrack.minidu.lk/widget.js"
  data-id="yoursite.com"
  data-position="center"></script>

Replace yoursite.com with your actual domain. The data-id must match the hostname exactly — tracking is rejected if there's a mismatch.

Script Attributes

All available data-* attributes for the widget script tag:

Attribute	Type	Default	Description
`data-id` required	string	`"default"`	Your site's domain (e.g. `mysite.com`). Must match the hostname exactly.
`data-position` optional	string	`"center"`	Horizontal alignment of the widget. Accepts `left`, `center`, or `right`.

Widget Positions

Control where the counter badge aligns inside its container element using data-position.

Left data-position="left"

Center data-position="center"

Right data-position="right"

The widget injects a wrapper <div> with width: 100% at the script's location. Place the script inside the container you want it aligned within.

Badges

Badge URLs

Embed a static visitor count badge — perfect for GitHub READMEs, npm pages, or any HTML page. The badge auto-updates on every load.

Platform	Usage
GitHub README	`![visitors](https://restless-frog-bb03.minidushashimal.workers.dev/badge/yoursite.com)`
HTML	`<img src="https://...workers.dev/badge/yoursite.com">`
npm / PyPI	`[![visitors](https://...workers.dev/badge/yoursite.com)](https://yoursite.com)`

Example snippets

Markdown (GitHub README)

![visitors](https://restless-frog-bb03.minidushashimal.workers.dev/badge/yoursite.com)

HTML

<img src="https://restless-frog-bb03.minidushashimal.workers.dev/badge/yoursite.com"
     alt="visitors">

Style Options (`?style=`)

Control the visual style of your badge with the ?style= query parameter.

visitors 1,234

flat (default)

GitHub Actions style with subtle gradient. Clean and widely recognised.

visitors 1,234

flat-square

No rounded corners. Sharp, modern look. Great for rectangular layouts.

visitors 1,234

for-the-badge

Tall, bold, uppercase. High impact. Popular in developer READMEs.

social

GitHub follower count style. Familiar social-media aesthetic.

Example

https://restless-frog-bb03.minidushashimal.workers.dev/badge/yoursite.com?style=flat-square

Extra Query Params

Combine multiple parameters to fully customise your badge's appearance.

URL

https://restless-frog-bb03.minidushashimal.workers.dev/badge/yoursite.com?style=flat-square&label=views&color=0ea5e9

Param	Default	Example
`style`	`flat`	`flat-square`
`label`	`visitors`	`page views`
`color`	`7c3aed` (purple)	`0ea5e9`, `22c55e`

Pass hex color values without the leading #. For example, use color=0ea5e9 not color=#0ea5e9.

Ownership

Verify Domain Ownership

Verifying your domain unlocks the full analytics dashboard — including visitor IPs, browser data, and country info. Verification uses DNS TXT records, so only the real domain owner can claim a site.

1

Request a verification token

Go to your dashboard and enter your domain + email. Click Generate. You'll receive a unique TXT record value.

2

Add the TXT record to your DNS

In your domain registrar or DNS provider, add a TXT record at @:

DNS TXT Record

Type:  TXT
Name:  @
Value: pasteltrack-verify=pt-xxxxxxxxxxxx-owner=xxxxxxxxxx

3

Click "Check DNS"

DNS propagation takes 5–30 minutes. Once detected, your domain is verified. A magic login link and your permanent Secret Key are emailed to you.

4

Replace with the permanent TXT record

After verification, replace the pasteltrack-verify=… record with the permanent ownership record: pasteltrack-owner=pts_xxxxxxxxxxxxxxxxxxxx

This lets you re-verify ownership in the future without re-doing the whole flow.

Only one email can verify a domain. If you use a different email, you'll get an "email mismatch" error. The verification token is tied to the first email used.

Secret Key Login

After domain verification, you receive a permanent Secret Key (format: ptsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx). This key never expires and lets you sign in to your full analytics dashboard at any time.

How to use your Secret Key

Navigate to your dashboard URL, click Owner Access, and enter your email + Secret Key. On success, you'll be granted full access — including IP addresses, country data, and invite management.

Your Secret Key is sensitive. Anyone with your email and Secret Key can access your full analytics. Store it securely — treat it like a password.

Magic Link Login

Every time you verify or re-confirm domain ownership, PastelTrack emails you a one-click login link valid for 15 minutes. Clicking it logs you into your dashboard instantly — no password needed.

Magic links are single-use. Once clicked (or expired), they stop working. Use your Secret Key for ongoing access.

Magic links redirect to your dashboard with your owner_secret in the URL. This is a session token — it's valid but scoped to your domain only.

Sharing

Invite Links (Read-Only)

Share a time-limited read-only view of your analytics with teammates or clients — without exposing your Secret Key or owner access.

Creating an invite link

In your dashboard under Settings → Invites, click New Invite. You can set an optional label and expiry (1–168 hours). The generated URL includes a token that grants read-only stats access.

Feature	Read-Only Invite	Full Owner Access
Today / yesterday counts	✅	✅
30-day chart	✅	✅
Browser & OS data	✅	✅
Country data	✅	✅
Visitor IP addresses	🚫 Hidden	✅ Visible
Invite management	🚫	✅
Key rotation	🚫	✅

Full Access Links

Generate a 30-day full-access link that grants complete owner-level access to the dashboard — including IPs, invite management, and key rotation. Useful for sharing with a trusted co-admin.

Full access links expose everything an owner can see. Only share with people you fully trust. You can revoke them anytime from Settings → Access Links.

API Reference

The PastelTrack API is hosted on Cloudflare Workers. Base URL:

https://restless-frog-bb03.minidushashimal.workers.dev

POST /track

POST /track Record a page visit

Called automatically by the widget. You typically don't need to call this manually.

Request Body (JSON)

{
  "siteId": "yoursite.com",     // required
  "url":    "https://yoursite.com/page", // optional
  "ref":    "https://google.com",  // optional, referrer
  "wm_ok":  true                   // watermark check
}

Response

{
  "count":      42,
  "online":     3,
  "new_visit":  true,
  "registered": false
}

GET /stats

GET /stats?id=yoursite.com Fetch analytics data

Returns site statistics. Access level depends on the parameters provided.

Parameter	Description
`id` required	Your site domain
`secret` optional	Owner secret for full access
`access` optional	Full access link token
`invite` optional	Read-only invite token

Full Access Response

{
  "count":     1234,
  "today":     87,
  "yesterday": 62,
  "online":    4,
  "since":     "2025-01-01",
  "bestDay":   "2025-03-14",
  "bestCount": 203,
  "last30":    { "2025-05-01": 45, /* … */ },
  "recent": [
    {
      "t": "2025-05-30 14:22",
      "r": "https://google.com",
      "ip": "1.2.3.4",
      "os": "macOS",
      "browser": "Chrome",
      "country": "LK"
    }
  ],
  "access_level": "full"
}

Auth Endpoints

POST /verify-domain Start DNS verification

Body: { "domain": "…", "email": "…" } — Returns TXT record to add to DNS.

GET /check-verify?domain=…&email=… Confirm DNS & send magic link

Checks if the TXT record is live. On success, emails the magic link + Secret Key.

POST /secret-login Authenticate with Secret Key

Body: { "domain": "…", "email": "…", "secret_key": "ptsk_…" } — Returns owner_secret on success.

POST /rotate-key Invalidate & regenerate Secret Key

Body: { "domain": "…", "email": "…", "secret": "owner_secret" } — Old key is invalidated. New key emailed.

POST /create-invite Generate a read-only invite link

Body: { "domain", "secret", "label", "expires_in_hours" } — Max 168 hours (7 days).

POST /generate-access-link Generate a 30-day full access link

Body: { "domain", "secret", "label" } — Returns a full-access URL valid for 30 days.

Security

Security Model

PastelTrack is designed to be as safe as possible for a public analytics tool.

Domain isolation

Tracking requests are validated against the Origin / Referer header. A site registered as mysite.com will reject pings from othersite.com — even with the correct data-id.

Secret key hashing

Secret Keys are never stored directly. Only a SHA-256 hash (with a fixed salt) is stored in the database. Even if the database is compromised, raw keys cannot be recovered.

IP hashing for sessions

Session keys used for deduplication are SHA-256 hashes of IP + User-Agent. The raw IP is only stored in the last 20 visits log, visible to verified owners only.

DNS ownership proof

Domain verification is cryptographically tied to a DNS TXT record. Only the actual domain owner (who controls DNS) can pass verification — phishing a different email won't work.

Rotate Your Secret Key

If you believe your Secret Key has been compromised, rotate it immediately. Go to Settings → Danger Zone → Rotate Secret Key. This instantly invalidates the old key and emails a new one.

Key rotation is irreversible. Any active sessions using the old key will be immediately invalidated. All full-access links remain valid (they use a different token).

Everything you need to get started

Quick Start

How It Works

Session deduplication

Online count

Bot filtering

Embed Code

Script Attributes

Widget Positions

Badge URLs

Example snippets

Style Options (?style=)

Extra Query Params

Verify Domain Ownership

Secret Key Login

How to use your Secret Key

Magic Link Login

Invite Links (Read-Only)

Creating an invite link

Full Access Links

API Reference

POST /track

GET /stats

Auth Endpoints

Security Model

Domain isolation

Secret key hashing

IP hashing for sessions

DNS ownership proof

Rotate Your Secret Key

Style Options (`?style=`)