JavaScript SDK

A lightweight JavaScript/TypeScript SDK for web applications.

Requirements

• Node.js 16+ (for build tools)
• Modern browser with ES2020 support, or Node.js runtime

Installation

npm install @mostly-good-metrics/javascript

Quick Start

Initialize

import { MostlyGoodMetrics } from '@mostly-good-metrics/javascript';

MostlyGoodMetrics.configure({
  apiKey: 'mgm_proj_your_api_key',
});

Track Events

// Simple event
MostlyGoodMetrics.track('button_clicked');

// Event with properties
MostlyGoodMetrics.track('purchase_completed', {
  product_id: 'SKU123',
  price: 29.99,
  currency: 'USD',
});

Identify Users

// Set user identity (optional - anonymous ID is auto-generated)
MostlyGoodMetrics.identify('user_123');

// Reset identity (e.g., on logout)
MostlyGoodMetrics.resetIdentity();

User Identification

The SDK automatically generates and persists an anonymous user_id (UUID) for each user:

• Auto-generated on first visit
• Persists across sessions (stored in cookies and localStorage)
• Included in every event as user_id

When you call identify(), the identified user ID takes precedence.

Cross-Subdomain Tracking

MostlyGoodMetrics.configure({
  apiKey: 'mgm_proj_your_api_key',
  cookieDomain: '.yourdomain.com', // Share across all subdomains
});

Privacy Mode (No Cookies)

MostlyGoodMetrics.configure({
  apiKey: 'mgm_proj_your_api_key',
  disableCookies: true, // Only use localStorage
});

Configuration Options

MostlyGoodMetrics.configure({
  apiKey: 'mgm_proj_your_api_key',
  baseURL: 'https://ingest.mostlygoodmetrics.com',
  environment: 'production',
  appVersion: '1.0.0',
  maxBatchSize: 100,
  flushInterval: 30,
  maxStoredEvents: 10000,
  enableDebugLogging: process.env.NODE_ENV === 'development',
  trackAppLifecycleEvents: true,
});

Option	Default	Description
apiKey	Required	Your API key
baseURL	https://ingest.mostlygoodmetrics.com	API endpoint
environment	"production"	Environment name
appVersion	-	App version (required for install/update tracking)
maxBatchSize	100	Events per batch
flushInterval	30	Auto-flush interval in seconds
enableDebugLogging	false	Enable console output
trackAppLifecycleEvents	false	Auto-track lifecycle events
cookieDomain	-	Cookie domain for cross-subdomain tracking
disableCookies	false	Disable cookies, use only localStorage
persistence	'localStorage+cookie'	Where state persists: 'localStorage+cookie', 'localStorage', or 'memory'
respectDoNotTrack	false	Treat browsers with DNT or GPC enabled as opted out (Privacy)
optedOutByDefault	false	Start opted out until optIn() is called (Privacy)
collectDeviceProperties	true	Collect device properties

Automatic Events

When trackAppLifecycleEvents is enabled:

Event	When	Properties
$app_installed	First visit (localStorage)	$version
$app_updated	Version change detected	$version, $previous_version
$app_opened	Page load / tab visible	-
$app_backgrounded	Tab hidden / page unload	-

Privacy

The SDK collects no advertising identifiers, no location, and nothing you don't explicitly pass to track() or identify(). identify() is optional — without it, users are tracked under a random, resettable anonymous ID ($anon_...).

Opt-out

MostlyGoodMetrics.optOut();      // stop all tracking immediately
MostlyGoodMetrics.optIn();       // resume tracking
MostlyGoodMetrics.isOptedOut();  // current state

While opted out, tracking calls are no-ops and queued (unsent) events are purged. The choice is persisted and survives page loads.

For consent-first sites (e.g. GDPR), start opted out and call optIn() after consent:

MostlyGoodMetrics.configure({
  apiKey: 'mgm_proj_your_api_key',
  optedOutByDefault: true, // no events until optIn() is called
});

A persisted opt-in/opt-out choice always wins over optedOutByDefault on later visits.

Do Not Track / Global Privacy Control

MostlyGoodMetrics.configure({
  apiKey: 'mgm_proj_your_api_key',
  respectDoNotTrack: true,
});

When enabled, browsers with Do Not Track (navigator.doNotTrack === '1') or Global Privacy Control (navigator.globalPrivacyControl === true) are treated as opted out automatically.

Persistence modes

MostlyGoodMetrics.configure({
  apiKey: 'mgm_proj_your_api_key',
  persistence: 'memory', // nothing written to disk
});

Mode	Behavior
'localStorage+cookie' (default)	localStorage plus a cookie (enables cross-subdomain tracking)
'localStorage'	No cookies — same as disableCookies: true
'memory'	Nothing persisted; IDs and the event queue live only for the page session

Rotating the anonymous ID

Rotate the anonymous ID so future events can't be linked to earlier anonymous activity:

const newId = MostlyGoodMetrics.resetAnonymousId();

Forget me

resetIdentity() clears the user ID (e.g. on logout); pass clearAnonymousId: true for a full local reset:

MostlyGoodMetrics.resetIdentity({ clearAnonymousId: true });

This clears the user ID, rotates the anonymous ID, purges pending events and super properties, and starts a new session.

Limiting device properties

MostlyGoodMetrics.configure({
  apiKey: 'mgm_proj_your_api_key',
  collectDeviceProperties: false,
});

Framework Integration

React

// src/analytics.ts
import { MostlyGoodMetrics } from '@mostly-good-metrics/javascript';

export function initAnalytics() {
  MostlyGoodMetrics.configure({
    apiKey: process.env.REACT_APP_MGM_API_KEY!,
    environment: process.env.NODE_ENV,
    appVersion: process.env.REACT_APP_VERSION,
  });
}

// src/index.tsx
import { initAnalytics } from './analytics';
initAnalytics();

Next.js

// lib/analytics.ts
import { MostlyGoodMetrics } from '@mostly-good-metrics/javascript';

export function initAnalytics() {
  if (typeof window !== 'undefined') {
    MostlyGoodMetrics.configure({
      apiKey: process.env.NEXT_PUBLIC_MGM_API_KEY!,
      environment: process.env.NODE_ENV,
    });
  }
}

// app/layout.tsx
'use client';
import { useEffect } from 'react';
import { initAnalytics } from '@/lib/analytics';

export default function RootLayout({ children }) {
  useEffect(() => {
    initAnalytics();
  }, []);

  return <html>...</html>;
}

Vue

// src/plugins/analytics.ts
import { MostlyGoodMetrics } from '@mostly-good-metrics/javascript';

export default {
  install() {
    MostlyGoodMetrics.configure({
      apiKey: import.meta.env.VITE_MGM_API_KEY,
      environment: import.meta.env.MODE,
    });
  }
};

// src/main.ts
import analytics from './plugins/analytics';
app.use(analytics);

TypeScript Support

Full TypeScript support with exported types:

import {
  MostlyGoodMetrics,
  MGMConfiguration,
  MGMEvent,
  EventProperties,
} from '@mostly-good-metrics/javascript';