@plainapps/analytics-core

Privacy-focused, cookie-free analytics tracking library. This core package provides the base functionality for all framework-specific implementations.

Features

• 🔒 Privacy-first: Cookie-free tracking using IP hashing
• 🚀 Lightweight: < 2KB gzipped
• 📦 Tree-shakable: Only import what you need
• 💪 TypeScript: Full type definitions included
• 🌐 Universal: Works in any JavaScript environment

Installation

npm install @plainapps/analytics-core
# or
yarn add @plainapps/analytics-core
# or
pnpm add @plainapps/analytics-core

Quick Start

import { init, event, goal } from '@plainapps/analytics-core';

// Initialize with your site key
init({ siteId: 'pwa_site_abc123' });

// Track custom events
event('signup', { plan: 'pro' });

// Track goal conversions
goal('purchase', { revenue: 9900 }); // revenue in cents

API Reference

Configuration

interface AnalyticsConfig {
  siteId: string;           // Required: Your site key (pwa_site_*)
  apiEndpoint?: string;     // Custom API endpoint
  autoPageview?: boolean;   // Auto-track pageview on init (default: true)
  hashMode?: boolean;       // Track hash changes as pageviews (default: false)
  debug?: boolean;          // Enable debug logging (default: false)
}

Functions

init(config: AnalyticsConfig): void

Initialize analytics with your configuration.

init({
  siteId: 'pwa_site_abc123',
  autoPageview: true,
  debug: false
});

pageview(url?: string): void

Manually track a pageview. If no URL is provided, uses the current page URL.

// Track current page
pageview();

// Track specific URL (e.g., for SPAs)
pageview('/dashboard');

event(name: string, properties?: EventProperties): void

Track a custom event with optional properties.

event('button_click', {
  button: 'signup',
  location: 'header'
});

goal(goalId: string, options?: GoalOptions): void

Track a goal conversion with optional revenue and properties.

goal('purchase', {
  revenue: 9900,  // in cents
  properties: {
    plan: 'pro',
    period: 'annual'
  }
});

setEnabled(enabled: boolean): void

Enable or disable tracking (e.g., for user opt-out).

// Disable tracking
setEnabled(false);

// Re-enable tracking
setEnabled(true);

isInitialized(): boolean

Check if analytics has been initialized.

getConfig(): AnalyticsConfig | null

Get the current configuration.

Creating Multiple Instances

For advanced use cases, you can create multiple analytics instances:

import { createAnalytics } from '@plainapps/analytics-core';

const analytics1 = createAnalytics();
analytics1.init({ siteId: 'site1' });

const analytics2 = createAnalytics();
analytics2.init({ siteId: 'site2' });

Framework Libraries

For easier integration with popular frameworks:

• @plainapps/analytics-react - React hooks and components
• @plainapps/analytics-vue - Vue 3 composables and plugin
• @plainapps/analytics-svelte - Svelte stores and components
• @plainapps/analytics-angular - Angular service and directives

License

MIT