Premely Analytics for JavaScript

The official zero-dependency browser SDK for Premely Analytics. Add privacy-first website analytics, conversion tracking and linked revenue context to JavaScript, TypeScript, React, Next.js, Vue and Svelte applications. It installs the same small tracker used by Premely's direct HTML and platform integrations. The only credential accepted in browser code is the revocable public pm_site_v1_… site key.

Install

npm install @premely/analytics

import { createPremely } from "@premely/analytics";

const analytics = createPremely({
  siteKey: "pm_site_v1_your_public_site_key",
  domain: "example.com",
});

await analytics.install(); // sends the initial pageview
analytics.track("Signup completed", { props: { plan: "pro" } });
analytics.track("Purchase", {
  event_id: "0198a000-0000-7000-8000-000000000003",
  occurred_at: "2025-08-12T20:36:51.328Z",
  revenue: { amount_minor: 1999, currency: "GBP" },
});

Calls made before the tracker finishes loading are bounded and drained once. Repeated install() calls with the same configuration reuse one script and one promise; an existing runtime must expose the same site/domain/collector fingerprint, and conflicting or unverifiable configuration is rejected. With the default respectDnt: true, a browser Do Not Track signal resolves installation as a deliberate no-op without loading the tracker or retaining queued events.

Consent managers can call setConsent(false) to clear unsent events immediately and stop pageviews, SPA history observation, page-exit delivery, and custom events. A later setConsent(true) resumes prospectively with a fresh pageview; events observed while consent was denied are never replayed. The standalone runtime exposes the equivalent window.premely.setConsent(boolean) control.

For retry-safe server-known conversions, supply event_id and occurred_at together. The ID must be UUIDv7 and the timestamp must be ISO-8601; partial or malformed identities fail closed. Reusing the exact pair allows the replay-safe reporting datasource to collapse network retries and page reloads. Never derive a browser-visible ID directly from an order/customer identifier—use opaque random or secret-HMAC entropy.

Do not send names, email addresses, full URLs, user IDs, or other personal data in custom properties. Property values are limited to short strings, finite numbers, booleans, and null; nested values are discarded. Page and referrer query strings are removed. Numeric IDs, UUIDs, high-entropy or unsafe segments, and every child below sensitive route families such as search, account, user, checkout, reset, invite, and authentication are grouped as :id before transmission. Safe public slugs such as product and blog paths remain available for reporting.

What appears in Premely

The SDK feeds Premely's shared provider-independent analytics pipeline. It does not create a separate npm dashboard or alternative metric definitions.

• Automatic pageviews and session lifecycle events contribute to Visitors, Bounce Rate and Average Session Time, plus page, referrer, UTM and device/browser breakdowns under the active site, date range, timezone and filters.
• track() records a bounded custom event. It contributes to Conversion Rate and may appear as a semantic chart event only when that event is configured as a goal and is relevant to the selected metric.
• A revenue object records an exact positive minor-unit amount and currency. It contributes to Revenue and Revenue / Visitor only after the shared revenue capability and deduplication checks accept it.
• A chart avatar is never inferred from browser data. Person-linked chart events require separate stable identity and deterministic linkage evidence; otherwise Premely shows the event without a person identity.
• Provider or custom events do not appear on every chart. The canonical event-relevance rules select only the events that genuinely explain the metric context, and the chart displays at most three in its compact bucket card before offering View all.

Collection acceptance is not proof that a chart is correct. Premely validates the canonical event, metric projection, capability evidence, query result and visible chart state before an integration is considered end-to-end complete.

Plain browser JavaScript

Use the browser export with an ESM-capable CDN after the package is published:

<script type="module">
  import { installPremely, track } from "https://esm.sh/@premely/analytics@0.1.1";
  await installPremely({ siteKey: "pm_site_v1_your_public_site_key" });
  document.querySelector("#signup").addEventListener("click", () => track("Signup"));
</script>

Alternatively import @premely/analytics/browser; it exposes the same API as window.Premely. The module does not install tracking until installPremely is called.

React, Next.js, Vue, Svelte, and routers

Call installPremely once in a client-only mount/hook. The function is SSR-safe and returns immediately on the server. The underlying tracker automatically observes pushState, replaceState, and popstate, so framework routes normally need no extra pageview hook. Use pageview() only when a framework changes rendered routes without updating browser history.

Local validation

npm test
npm run build
npm pack --dry-run

For an end-to-end local collector test:

installPremely({
  siteKey: "pm_site_v1_your_local_public_key",
  environment: "local",
  localTrackerOrigin: "http://localhost:8788",
  localCollectorOrigin: "http://localhost:8787",
});

Local mode deliberately accepts loopback HTTP only. Production and staging hosts are fixed in source.

Publishing accounts

No account is needed to build, test, or install this package from a local path. Publishing @premely/analytics requires an npm account with rights to the @premely organisation and 2FA or an appropriately scoped publishing token. Run npm publish --access public; the package is configured for public access and provenance.

Publisher, support and legal

@premely/analytics is the official Premely Analytics SDK, published under the Premely product identity.

• JavaScript SDK documentation
• npm package
• Premely privacy notice
• Premely terms of service
• Contact support
• MIT licence

Release checklist

1. Update the version in package.json and src/browser.ts.
2. Run npm run prepack and inspect the dry-run file list for secrets or unwanted files.
3. Test a consumer using npm install /absolute/path/to/packages/tracker.
4. Publish with provenance, then smoke-test both package exports in a clean project.