Developer Documentation Summary

By Sufyaan Studio Research•Verified August 2026

Analytics by Sufyaan Studio provides an ultra-lightweight (1.15 KB gzipped), cookie-free JavaScript client and REST API. Install via a single script tag with defer for automatic SPA pageview capture, or use window.analytics.track() for custom conversion events.

KEY TAKEAWAYS

Universal script tag installation in under 2 minutes
Automatic SPA history pushState/replaceState tracking
Full custom event properties API (2 KB JSON payload capacity)
Automatic UTM marketing source and ad click ID attribution

01 // GETTING STARTED

One-Line Quickstart

Add the lightweight script tag inside the <head> of your website. The script runs asynchronously, weighs 1.15 KB gzipped (≤1.5 KB budget, 0 dependencies), and does not block page rendering. Uses sendBeacon → fetch(keepalive) fallback.

UNIVERSAL HTML SNIPPET

<script
  defer
  src="https://yourdomain.com/t.js"
  data-web="13921d15-5a3b-4b3d-ae89-b49255ee3381"
></script>

REQUIRED

data-web

Your website UUID. Pageviews auto-tracked, SPA via pushState.

OPTIONAL

data-host

Custom collector origin. Defaults to script origin + /c.

OPTIONAL

data-dev="true"

Allow localhost / 127.0.0.1 / *.local.

OPTIONAL

data-respect-dnt="true"

Honor navigator.doNotTrack=1.

Auto-captured per pageview: url (pathname) + query (?utm_*) + referrer + title + screen + language + hostname. UTM/click-IDs extracted server-side, referrer self-check drops your own domain.

02 // FRAMEWORKS & LANGUAGES

Frontend Framework Integrations

Select your framework to view tailored copy-paste implementation snippets.

Next.js (App Router & Pages Router)

DIRECT

Add the Script component in your root layout for automatic SPA route change tracking.

NEXTJS IMPLEMENTATION

// app/layout.tsx (App Router)
import Script from 'next/script';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <head>
        <Script
          defer
          src="https://analytics-collect.sufyaanstudio.workers.dev/t.js"
          data-web="YOUR_WEBSITE_ID"
          strategy="afterInteractive"
        />
      </head>
      <body>{children}</body>
    </html>
  );
}

03 // EVENT TRACKING API

Custom Events & Conversion Tracking

Track custom user interactions like signup buttons, modal triggers, billing tier upgrades, and checkout completions using window.analytics.track().

EVENT TRACKING API SYNTAX

// Signature:
// window.analytics.track(eventName: string, properties?: Record<string, any>)

// 1. Basic Button Click Event:
window.analytics.track('pricing_cta_clicked');

// 2. Custom Conversion Event with Metadata:
window.analytics.track('user_signed_up', {
  plan: 'pro_monthly',
  source: 'header_banner',
  currency: 'USD',
  amount: 29
});

// 3. E-commerce Checkout Completed:
window.analytics.track('purchase_success', {
  order_id: 'ord_987654',
  items_count: 3,
  value: 149.50
});

Event Validation & Payload Limits (server-enforced):

• Name limit: 128 chars (trimmed, p_event_name). Names starting with = + - @ rejected (CSV injection guard).
• Properties payload: 2 KB JSON (`pg_column_size` cap) — objects kept, arrays/scalars wrapped as {value: ...}, oversized truncated server-side.
• Path/Title/Query caps: 1024 / 512 / 512 chars. Bot User-Agents dropped, empty UA dropped.
• Dedupe: Identical payload within 1s (client) + same-path pageview within 1s (server, only if last event was pageview) debounced.
• Queue: 200 ms batch window, max 10 events/request, sendBeacon → fetch keepalive, flushed on visibilitychange/pagehide.

04 // INTERACTIVE GENERATOR

Generate Custom Event Code

Enter your event details to generate live snippets in JavaScript, Node.js, Python, PHP, and cURL.

EVENT NAME

PROPERTY KEY

PROPERTY VALUE

CLIENT JAVASCRIPT CODE

// Dispatch in frontend:
window.analytics.track('upgrade_plan_selected', {
  tier: 'enterprise'
});

05 // READY-TO-USE RECIPES

Common Tracking Recipes

Plug-and-play patterns for tracking clicks, forms, scroll depth, and modal engagement.

CLICK & SCROLL DEPTH TRACKING

// 1. Track all button clicks automatically:
document.querySelectorAll('button, .btn').forEach(btn => {
  btn.addEventListener('click', () => {
    window.analytics?.track('button_click', {
      text: btn.innerText.trim(),
      id: btn.id || null
    });
  });
});

// 2. Track scroll depth milestones (25%, 50%, 75%, 100%):
let maxScroll = 0;
window.addEventListener('scroll', () => {
  const depth = Math.round((window.scrollY + window.innerHeight) / document.body.scrollHeight * 100);
  [25, 50, 75, 100].forEach(milestone => {
    if (depth >= milestone && maxScroll < milestone) {
      maxScroll = milestone;
      window.analytics?.track('scroll_depth', { percent: milestone });
    }
  });
});

// 3. Track modal open & close:
function openModal(modalName) {
  window.analytics?.track('modal_opened', { modal: modalName });
}

06 // BACKEND & API

Server-Side Event Ingestion

Send events from your backend, webhooks, CLI tools, or serverless workers by sending a POST /c request.

NODE SERVER EXAMPLE

// Track backend events or webhook conversions — UTM auto-extracted from q
async function trackEvent(websiteId, eventName, urlPath, queryString = '', properties = {}) {
  await fetch('https://yourdomain.com/c', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      w: websiteId,
      n: eventName,                 // 'pageview' or custom name (≤128 chars, no =+-@)
      u: urlPath,                   // '/pricing' — pathname only
      q: queryString,               // '?utm_source=google&utm_medium=cpc&gclid=xyz' — UTMs parsed server-side
      r: 'https://google.com/',     // referrer — host extracted, self-referrals dropped
      t: 'Pricing',                 // title — 512 chars, formula-guarded
      p: properties                 // 2 KB JSON
    })
  });
}

// Example usage:
await trackEvent('YOUR_WEBSITE_ID', 'upgrade_plan_selected', '/checkout', '?utm_source=google&utm_medium=cpc', {
  tier: 'enterprise',
  amount: 240
});

Payload keys: w website UUID, n event name (null=pageview), u pathname, q query (UTMs auto-parsed → utm_source etc), r referrer (host+path extracted, self dropped), t title, p JSON props (2 KB). Server IP/UA/Country derived from headers (11 headers, CIDR block via IGNORE_IP), hostname from Origin/Referer.

07 // UTM & CHANNEL ATTRIBUTION

UTM & Channel Attribution

Marketing attribution is automatic. Every pageview captures utm_source / utm_medium / utm_campaign / utm_content / utm_term and click IDs gclid / fbclid / msclkid / ttclid / li_fat_id / twclid from the URL query string. No code change needed — just use tagged URLs.

EXAMPLE TAGGED URL

https://yourdomain.com/pricing?utm_source=google&utm_medium=cpc&utm_campaign=spring_sale&utm_content=hero_cta&gclid=abc123

DASHBOARD

Top Channels (utm_source)

Overview → Channels panel. Filtered by date range and drill-down. Export includes channels CSV.

API

get_top_utm_sources(website_id, start, end)

Also: utm_medium, utm_campaign. Public share uses get_public_top_utm_sources.

What is stored per pageview:

• utm_source utm_medium utm_campaign — truncated to 255 chars, indexed.
• referrer_path / referrer_query — full referrer path alongside host, self-referrals nulled.
• hostname — per-event host for multi-domain allowed_domains.
• Privacy: raw IP never stored, visitor_hash salted, all fields capped server-side. See dashboard Filters for retention-bound breakdowns.

08 // DEBUGGING & LOCAL TESTING

Testing & Troubleshooting

How to verify event delivery in local files, development servers, and staging environments.

1. Testing on Local Files (`file:///...`)

When opening local HTML files directly, the tracker automatically detects the script source origin (e.g. http://localhost:3000) and routes events via CORS.

2. Check the Browser Network Tab

Open Browser DevTools (F12 or Cmd+Opt+I) $\rightarrow$ Network. Filter by /c to see the outgoing POST request returning 204 No Content.

3. Trigger Events via DevTools Console

Type window.analytics.track('test_event', { user: 'tester' }) in your browser console to immediately verify event delivery.

09 // BEST PRACTICES & SECURITY

Content Security Policy (CSP) & Proxying

If your website enforces strict Content Security Policy headers, add our origin to your directives:

CSP HEADERS

# Content-Security-Policy header
Content-Security-Policy: script-src 'self' https://yourdomain.com; connect-src 'self' https://yourdomain.com;

10 // NATIVE ANDROID MOBILE APPv2.1.0 APK

Official Android App & APK Sideloading

Analytics by Sufyaan Studio offers an official high-performance native Android application built with React Native and the Hermes engine. It features native 60fps charts, sub-50ms cold start, persistent offline caching, hardware Keystore biometric encryption, and in-app self-updating.

OFFICIAL DIRECT DISTRIBUTION

Download Analytics v2.1.0 APK (76.0 MB)

Universal signed APK for Android 10 through 15. Distributed exclusively via our official website to eliminate Google Play store telemetry.

Download APK QR Code & Guide →

CLI DOWNLOAD & SHA-256 VERIFICATION

# 1. Download official APK (GitHub Release — direct, mobile-safe)
curl -L -o Analytics-v2.0.0.apk https://github.com/dev-sufyaan/Analytics/releases/download/v2.1.0/Analytics-v2.0.0.apk

# 2. Verify SHA-256 Checksum
sha256sum Analytics-v2.0.0.apk
# Expected: aef10c9f8be64ffb54df526f0e4e45350a9f504fcb4d2a511a36dfde58ada839

# 3. Optional: Install via ADB directly to a connected device
adb install -r Analytics-v2.0.0.apk

SECURITY

Hardware Keystore

Biometric Fingerprint & Face Unlock using Android hardware enclave.

NOTIFICATIONS

Daily Digest & Spikes

Receive automated traffic spike notifications powered by FCM topics.

UPDATES

In-App Self-Updater

Checks releases bucket on startup and installs in-place with 1 tap.

Integration & Event API Reference

One-Line Quickstart

Frontend Framework Integrations

Next.js (App Router & Pages Router)

Custom Events & Conversion Tracking

Event Validation & Payload Limits (server-enforced):

Generate Custom Event Code

Common Tracking Recipes

Server-Side Event Ingestion

UTM & Channel Attribution

What is stored per pageview:

Testing & Troubleshooting

1. Testing on Local Files (file:///...)

2. Check the Browser Network Tab

3. Trigger Events via DevTools Console

Content Security Policy (CSP) & Proxying

Official Android App & APK Sideloading

Download Analytics v2.1.0 APK (76.0 MB)

1. Testing on Local Files (`file:///...`)