@tiny-mv/analytics

Browser-first Tiny Analytics SDK for Tiny-hosted ingest endpoints.

What it is

@tiny-mv/analytics is the client-side SDK for Tiny Analytics. It gives product teams a simple way to initialize Tiny in a website or app, send custom events, and capture pageviews without pushing Tiny control-plane concerns into the browser runtime.

It ships in two forms:

• npm package: @tiny-mv/analytics
• hosted browser bundle: /sdk.js with the myux(...) command

Both forms share the same runtime behavior and the same event-envelope contract.

What it does

The SDK is responsible for the browser-side part of analytics collection:

• validating init config before network activity starts
• bootstrapping the browser against Tiny ingest
• creating or reusing anonymous visitor and session identity
• capturing custom events
• capturing pageviews, including SPA navigation when enabled
• queueing events client-side
• batching and sending events to Tiny ingest
• retrying failed uploads on a short delay
• flushing queued data on page exit where the browser allows it

The SDK is intentionally narrow. It does not include source provisioning, setup wizard UX, install-code generation, or built-in consent management.

Public API

The supported root runtime helpers for 1.x are:

• initTinyAnalytics(config)
• track(name, props?)
• trackPageView(path?, props?)

The supported hosted browser command surface is:

• myux("init" | "track" | "page", ...)

myux is the documented browser command for v1. The browser bundle also assigns the same dispatcher to window.tinyAnalytics as a legacy alias, but that alias is not the frozen contract.

Supported environments

• Browser bundlers such as Vite
• Client-side React apps
• Client-side Next.js usage
• Tiny-hosted <script src=".../sdk.js"> installs

Unsupported runtime target:

• Node/server execution of the analytics runtime

The package is ESM-only. Importing it is SSR-safe, but initTinyAnalytics() must run in a browser-like client environment.

Install

npm install @tiny-mv/analytics

Quickstart

import { initTinyAnalytics, track } from "@tiny-mv/analytics";

await initTinyAnalytics({
  publicKey: "pk_123456789abc",
  apiBaseUrl: "https://your-tiny-api",
  autoPageviews: true,
});

track("upgrade_clicked", { plan: "pro" });

Browser snippet

<script>
  window.myux =
    window.myux ||
    function () {
      (window.myux.q = window.myux.q || []).push(arguments);
    };
</script>
<script src="https://your-tiny-api/sdk.js" async></script>
<script>
  myux("init", {
    publicKey: "pk_123456789abc",
    apiBaseUrl: "https://your-tiny-api",
    autoPageviews: true
  });
</script>

How it works

At a high level, the SDK follows this lifecycle:

1. Your app imports the SDK. Import is side-effect free. The SDK does not touch window, localStorage, or the network just because it was imported.

2. Your app calls initTinyAnalytics(config). The SDK validates publicKey, normalizes apiBaseUrl, checks that it is running in a browser-like environment, and prevents conflicting re-initialization.

3. The SDK bootstraps with Tiny ingest. It sends a bootstrap request to /api/ingest/v2/:publicKey/bootstrap so the API can confirm the source, return session metadata, and associate the browser with the correct tracking source.

4. The SDK starts collecting browser-side analytics state. It creates or reuses an anonymous visitor id, restores a still-valid session if one exists, sets up page navigation listeners, and optionally sends the initial pageview.

5. Calls to track() and trackPageView() become queued event payloads. Each event is normalized into Tiny's shared envelope with event metadata, page context, anonymous id, optional userId, session id, library version, locale, timezone, and screen information when available.

6. The SDK flushes events to Tiny ingest. Events are sent in batches to /api/ingest/v2/:publicKey/events, with retries and unload-safe delivery behavior where possible.

Config and validation

initTinyAnalytics(config) expects a browser-oriented config object.

• publicKey is required and must look like pk_<token>
• apiBaseUrl is optional only when location.origin is available in the browser
• apiBaseUrl, when provided, must be an absolute http or https URL
• autoPageviews defaults to true
• debug enables structured SDK debug logging
• userId and orgId are optional metadata fields included in runtime context and events

Runtime semantics

The current runtime semantics are:

• session reuse window: 30 minutes
• persistence: anonymous visitor id, session metadata, identified user id, and queued events use localStorage when available
• queue batch size: up to 20 events per request
• flush cadence: every 5 seconds while work is queued
• page dedupe window: identical pageviews within 500ms are collapsed
• unload delivery: sendBeacon first, fetch(..., { keepalive: true }) fallback
• retry behavior: failed uploads are re-queued and retried after 2 seconds
• delivery guarantees: best-effort only; duplicates and event loss are both possible
• consent: no built-in consent manager; gate init and tracking in your app if required

If localStorage is blocked or unavailable, the SDK still runs, but persistence becomes in-memory only for that page lifetime.

Data flow

The SDK sends two kinds of requests:

• bootstrap request: establishes source/session state and confirms ingest setup
• event batch request: sends queued track and page_view events to Tiny

On page exit, the SDK tries sendBeacon first and falls back to fetch(..., { keepalive: true }).

Validation and failure policy

The SDK is designed to fail clearly on bad setup and degrade gracefully during runtime:

• invalid init config throws immediately
• missing or malformed publicKey values are rejected
• repeated init with the same normalized config reuses the existing runtime
• repeated init with a conflicting config throws and never silently switches destination
• track() and trackPageView() before init do not crash the app
• pre-init calls are held in memory and replayed after a successful init
• failed event uploads are re-queued and retried

What the SDK does not do

The SDK does not currently provide:

• built-in consent controls
• server-side analytics runtime support
• framework-specific adapters beyond the core API
• guaranteed once-only delivery
• control-plane workflows such as source creation or install snippet authoring

Why this shape matters

The SDK is deliberately small because analytics SDKs become hard to evolve once too much surface area is public. Tiny's v1 package keeps the contract focused on initialization, event capture, page capture, session handling, and transport. That gives customers a stable install path while keeping room to evolve the app, docs, and control plane independently.

Compatibility policy

• The first public npm release is 1.0.0
• The npm SDK and hosted /sdk.js share one event-envelope contract for 1.x
• Breaking API or envelope changes require a new major release
• Additive options and additive event metadata are minor-safe
• Deprecations require documentation, debug warnings, and at least one minor release plus 90 days before removal, except for urgent security fixes

See RELEASE.md in the repo for the publish and release checklist.