trykept-analytics

v2.0.0

Published

6 months ago

Advanced, privacy-friendly analytics tracking library with error tracking, form analytics, e-commerce, A/B testing, and Core Web Vitals support

Downloads

trykept-analytics

Advanced, privacy-friendly analytics tracking library with comprehensive features for modern web applications.

Features

Core Analytics - Pageviews, goals, events, scroll depth, engagement time
Error Tracking - JavaScript errors and unhandled promise rejections
Form Analytics - Field focus, abandonment, completion tracking
Rage Click Detection - Detect user frustration patterns
Core Web Vitals - LCP, FID, CLS, TTFB, FCP, INP
E-commerce Tracking - Product views, cart, checkout, purchases
Video/Audio Tracking - Play, pause, progress, completion
Heatmap Data - Click coordinates for visualization
Element Visibility - Track when elements enter viewport
A/B Testing - Experiment tracking and variant assignment
Offline Queue - Retry events when connection restores
Consent Management - Built-in GDPR-friendly consent handling
Bot Detection - Automatic filtering of bot traffic
Privacy-Focused - No cookies, respects DNT, GDPR-compliant

Installation

Via NPM / Yarn / PNPM

# npm
npm install trykept-analytics

# yarn
yarn add trykept-analytics

# pnpm
pnpm add trykept-analytics

Via CDN (unpkg)

<script defer
  data-website-id="YOUR_WEBSITE_ID"
  src="https://unpkg.com/[email protected]/dist/tracker.min.js">
</script>

Via CDN (jsDelivr)

<script defer
  data-website-id="YOUR_WEBSITE_ID"
  src="https://cdn.jsdelivr.net/npm/[email protected]/dist/tracker.min.js">
</script>

Available CDN Files

| File | Size | Use Case | |------|------|----------| | tracker.min.js | ~8 KB | Production (recommended) | | tracker.js | ~25 KB | Development / Debugging | | tracker.esm.js | ~25 KB | ES Modules | | tracker.umd.js | ~26 KB | AMD / CommonJS |

Self-Hosting

Download the tracker and host it on your own server:

# Download latest version
curl -o tracker.min.js https://unpkg.com/[email protected]/dist/tracker.min.js

Then serve from your domain:

<script defer
  data-website-id="YOUR_WEBSITE_ID"
  data-endpoint="https://your-analytics-server.com/api/event"
  src="/js/tracker.min.js">
</script>

Quick Start

Script Tag (Recommended for simplicity)

<script defer
  data-website-id="YOUR_WEBSITE_ID"
  data-endpoint="https://your-analytics-server.com/api/event"
  data-spa="true"
  data-scroll-tracking="true"
  data-engagement-time="true"
  data-web-vitals="true"
  src="/js/tracker.js">
</script>

ES Module

import { tracker } from 'trykept-analytics';

// Initialize
tracker.init({
  websiteId: 'YOUR_WEBSITE_ID',
  endpoint: 'https://your-analytics-server.com/api/event',
  spaMode: true,
  trackScroll: true,
  trackEngagement: true,
  trackWebVitals: true
});

// Track events
tracker.trackPageview();
tracker.trackGoal('Signup', 99.99);
tracker.trackEvent('button_click', { buttonId: 'cta' });

CommonJS

const { tracker } = require('trykept-analytics');

tracker.init({
  websiteId: 'YOUR_WEBSITE_ID',
  endpoint: 'https://your-analytics-server.com/api/event'
});

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | websiteId | string | required | Your unique website identifier | | endpoint | string | required | API endpoint URL | | autoTrack | boolean | true | Automatically track pageviews | | spaMode | boolean | false | Enable SPA history-based routing | | hashMode | boolean | false | Track hash changes | | trackOutbound | boolean | false | Track outbound link clicks | | trackDownloads | boolean | false | Track file downloads | | trackScroll | boolean | false | Track scroll depth milestones | | trackEngagement | boolean | false | Track time on page | | trackErrors | boolean | false | Track JavaScript errors | | trackForms | boolean | false | Track form interactions | | trackRageClicks | boolean | false | Detect rage clicks | | trackHeatmap | boolean | false | Collect click coordinates | | trackWebVitals | boolean | false | Track Core Web Vitals | | trackVisibility | boolean | false | Track element visibility | | trackMedia | boolean | false | Track video/audio playback | | trackCopy | boolean | false | Track copy events | | trackPrint | boolean | false | Track print events | | respectDNT | boolean | true | Respect Do Not Track | | excludePaths | string[] | [] | Paths to exclude (glob patterns) | | maskText | boolean | false | Mask text in events | | maskInputs | boolean | true | Mask input names | | useLocalStorage | boolean | true | Use localStorage for visitor ID | | sessionTimeout | number | 1800 | Session timeout (seconds) | | batchEvents | boolean | false | Batch events for sending | | batchSize | number | 10 | Events per batch | | batchInterval | number | 5000 | Batch interval (ms) | | offlineQueue | boolean | true | Queue events when offline | | maxQueueSize | number | 100 | Max queue size | | requireConsent | boolean | false | Require consent before tracking | | debug | boolean | false | Enable debug logging |

HTML Data Attributes

Enable features directly in HTML:

<script defer
  data-website-id="YOUR_ID"
  data-endpoint="https://your-server.com/api/event"
  data-auto-track="true"
  data-spa="true"
  data-hash-mode="false"
  data-outbound-links="true"
  data-file-downloads="true"
  data-scroll-tracking="true"
  data-engagement-time="true"
  data-error-tracking="true"
  data-form-tracking="true"
  data-rage-clicks="true"
  data-heatmap="true"
  data-web-vitals="true"
  data-media-tracking="true"
  data-copy-tracking="true"
  data-print-tracking="true"
  data-respect-dnt="true"
  data-exclude-paths="/admin/*,/preview/*"
  data-mask-text="false"
  data-session-timeout="1800"
  data-batch-events="false"
  data-offline-queue="true"
  data-require-consent="false"
  data-debug="false"
  src="/js/tracker.js">
</script>

API Reference

Core Tracking

// Track pageview
tracker.trackPageview();
tracker.trackPageview({ category: 'blog' });

// Track goal/conversion
tracker.trackGoal('Newsletter Signup');
tracker.trackGoal('Purchase', 99.99);
tracker.trackGoal('Subscription', 29.99, { plan: 'pro' });

// Track custom event
tracker.trackEvent('button_click', { buttonId: 'cta-hero' });
tracker.trackEvent('video_started', { videoId: 'intro' });

// Identify user
tracker.identify('[email protected]');
tracker.identify('user_123', { plan: 'pro', company: 'Acme' });

// Reset (logout)
tracker.reset();

HTML Attribute Tracking

<!-- Track goal on click -->
<button data-track-goal="Signup">Sign Up Free</button>

<!-- Track goal with value -->
<button data-track-goal="Purchase" data-track-value="49.99">Buy Now</button>

<!-- Track custom event -->
<button data-track-event="cta_click" data-track-data='{"variant": "A"}'>Click Me</button>

Custom Data

// Set persistent custom data
tracker.setCustomData({ 
  plan: 'pro',
  trial: false,
  referral: 'partner123'
});

// Get custom data
const data = tracker.getCustomData();

// Clear custom data
tracker.clearCustomData();

Error Tracking

// Auto-tracking (enable with trackErrors: true)
// Automatically captures window.onerror and unhandledrejection

// Manual error tracking
try {
  riskyOperation();
} catch (error) {
  tracker.trackError(error, {
    custom: { operation: 'checkout' }
  });
}

E-commerce Tracking

// Product view
tracker.ecommerce.trackProductView({
  id: 'SKU123',
  name: 'Premium Widget',
  category: 'Widgets',
  price: 29.99,
  currency: 'USD'
});

// Add to cart
tracker.ecommerce.trackAddToCart({
  id: 'SKU123',
  name: 'Premium Widget',
  price: 29.99,
  quantity: 2
});

// Remove from cart
tracker.ecommerce.trackRemoveFromCart({
  id: 'SKU123',
  quantity: 1
});

// Checkout start
tracker.ecommerce.trackCheckoutStart({
  total: 89.97,
  currency: 'USD',
  items: [/* products */]
});

// Checkout step
tracker.ecommerce.trackCheckoutStep(2, { payment_method: 'card' });

// Purchase
tracker.ecommerce.trackPurchase({
  id: 'ORDER-123',
  total: 89.97,
  currency: 'USD',
  paymentMethod: 'card',
  tax: 7.20,
  shipping: 5.99,
  items: [/* products */]
});

A/B Testing

// Set experiment variant
tracker.experiments.set('pricing-page', 'variant-b');

// Get current variant
const variant = tracker.experiments.get('pricing-page');

// Track experiment conversion
tracker.experiments.trackConversion('pricing-page', 'signup', 29.99);

Media Tracking

// Auto-tracking (enable with trackMedia: true)
// Automatically tracks all video/audio elements

// Manual tracking
const video = document.querySelector('#promo-video');
tracker.trackMedia(video, { campaign: 'launch' });

Element Visibility

// Track when elements become visible
tracker.trackVisibility('.pricing-section', {
  threshold: 0.5,       // 50% visible
  once: true,           // Track only first time
  eventName: 'pricing_viewed'
});

tracker.trackVisibility('[data-track-visible]', {
  threshold: 0.75,
  customData: { page: 'landing' }
});

Search Tracking

// Track site search
tracker.trackSearch('analytics tools', 42);

Consent Management

// Check if consent is required
if (tracker.consent.required()) {
  // Show consent banner
}

// Give consent
tracker.consent.give(['necessary', 'analytics']);
tracker.consent.give(); // All categories

// Revoke consent
tracker.consent.revoke();

// Check consent
if (tracker.consent.has('analytics')) {
  // Can track analytics
}

Engagement Tracking

// Manual engagement control
tracker.startEngagement();
tracker.pauseEngagement();

Utilities

// Get visitor ID
const visitorId = tracker.getVisitorId();

// Get session ID
const sessionId = tracker.getSessionId();

// Get version
console.log(tracker.version); // "2.0.0"

// Debug info
tracker.debug();

Framework Integration

React

// hooks/useAnalytics.js
import { useEffect } from 'react';
import { tracker } from 'trykept-analytics';

export function useAnalytics() {
  useEffect(() => {
    tracker.init({
      websiteId: process.env.REACT_APP_ANALYTICS_ID,
      endpoint: process.env.REACT_APP_ANALYTICS_ENDPOINT,
      spaMode: true
    });
  }, []);

  return tracker;
}

// Usage in component
function App() {
  const analytics = useAnalytics();
  
  const handleSignup = () => {
    analytics.trackGoal('Signup');
  };
  
  return <button onClick={handleSignup}>Sign Up</button>;
}

Vue.js

// plugins/analytics.js
import { tracker } from 'trykept-analytics';

export default {
  install(app, options) {
    tracker.init(options);
    app.config.globalProperties.$analytics = tracker;
    app.provide('analytics', tracker);
  }
};

// main.js
import analytics from './plugins/analytics';
app.use(analytics, {
  websiteId: import.meta.env.VITE_ANALYTICS_ID,
  endpoint: import.meta.env.VITE_ANALYTICS_ENDPOINT,
  spaMode: true
});

// Component usage
import { inject } from 'vue';
const analytics = inject('analytics');
analytics.trackGoal('Purchase', 99.99);

Next.js

// app/providers.js
'use client';
import { useEffect } from 'react';
import { tracker } from 'trykept-analytics';

export function AnalyticsProvider({ children }) {
  useEffect(() => {
    tracker.init({
      websiteId: process.env.NEXT_PUBLIC_ANALYTICS_ID,
      endpoint: process.env.NEXT_PUBLIC_ANALYTICS_ENDPOINT,
      spaMode: true
    });
  }, []);

  return children;
}

// app/layout.js
import { AnalyticsProvider } from './providers';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <AnalyticsProvider>{children}</AnalyticsProvider>
      </body>
    </html>
  );
}

Nuxt 3

// plugins/analytics.client.js
import { tracker } from 'trykept-analytics';

export default defineNuxtPlugin(() => {
  tracker.init({
    websiteId: useRuntimeConfig().public.analyticsId,
    endpoint: useRuntimeConfig().public.analyticsEndpoint,
    spaMode: true
  });

  return {
    provide: {
      analytics: tracker
    }
  };
});

// Usage
const { $analytics } = useNuxtApp();
$analytics.trackGoal('Purchase', 99.99);

Privacy & GDPR

This library is designed with privacy in mind:

No Cookies - Uses localStorage/sessionStorage by default
Respects DNT - Honors Do Not Track browser setting
IP Anonymization - Server-side only, not stored
Consent Management - Built-in consent handling
Data Minimization - Collects only necessary data
Text Masking - Option to mask sensitive text

GDPR Compliance

// Enable consent requirement
tracker.init({
  // ...
  requireConsent: true,
  consentCategories: ['necessary', 'analytics', 'marketing']
});

// After user gives consent
tracker.consent.give(['necessary', 'analytics']);

// User revokes consent
tracker.consent.revoke();

TypeScript Support

Full TypeScript support included:

import { tracker, TrackerConfig, Product, Order } from 'trykept-analytics';

const config: TrackerConfig = {
  websiteId: 'YOUR_ID',
  endpoint: 'https://your-server.com/api/event',
  trackWebVitals: true
};

tracker.init(config);

const product: Product = {
  id: 'SKU123',
  name: 'Widget',
  price: 29.99
};

tracker.ecommerce.trackProductView(product);

Browser Support

Chrome 60+
Firefox 55+
Safari 12+
Edge 79+
Opera 47+

License

MIT License - see LICENSE for details.

Support

Documentation: https://analytics.trykept.co/docs
Issues: GitHub Issues
Email: [email protected]

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

trykept-analytics

Features

Installation

Via NPM / Yarn / PNPM

Via CDN (unpkg)

Via CDN (jsDelivr)

Available CDN Files

Self-Hosting

Quick Start

Script Tag (Recommended for simplicity)

ES Module

CommonJS

Configuration Options

HTML Data Attributes

API Reference

Core Tracking

HTML Attribute Tracking

Custom Data

Error Tracking

E-commerce Tracking

A/B Testing

Media Tracking

Element Visibility

Search Tracking

Consent Management

Engagement Tracking

Utilities

Framework Integration

React

Vue.js

Next.js

Nuxt 3

Privacy & GDPR

GDPR Compliance

TypeScript Support

Browser Support

License

Support