GAtor

A lightweight Google Analytics 4 tracking library for TypeScript, providing a simple and type-safe way to implement GA4 event tracking with support for generic events and triggers.

Features

• 🎯 Type-safe GA4 tracking - Full TypeScript support with proper type definitions
• 🔄 Generic events - Automatically trigger additional events based on action patterns
• 🛡️ Error handling - Graceful error handling for all GA operations
• 📦 Lightweight - Minimal bundle size with no unnecessary dependencies
• 🚀 Easy integration - Simple API that works with any React or vanilla JS project

Installation

npm install @mirawision/gator react-ga4

Quick Start

import { GAtor } from '@mirawision/gator';

// Initialize GAtor with your GA4 tracking ID
const gator = new GAtor({
  trackingId: 'G-XXXXXXXXXX'
});

// Track a page view
gator.trackPageView();

// Track an event
gator.trackEvent({
  category: 'User Interaction',
  action: 'button_click',
  label: 'signup_button'
});

API Reference

GAtor Constructor

new GAtor(config: GAtorConfig)

Parameters:

• config.trackingId (string, required): Your Google Analytics 4 tracking ID
• config.events (GAEventMap, optional): Predefined event functions
• config.genericEvents (GenericGAEvent[], optional): Generic events that trigger based on action patterns

Methods

trackPageView()

Tracks the current page view using the current URL.

trackEvent(event: GAEvent)

Tracks a custom event.

Parameters:

• event.category (string, required): Event category
• event.action (string, required): Event action
• event.label (string, optional): Event label
• event[key] (any, optional): Additional custom parameters

Types

GAEvent

interface GAEvent {
  category: string;
  action: string;
  label?: string;
  [key: string]: any;
}

GenericGAEvent

interface GenericGAEvent {
  event: GAEvent;
  triggers: string[];
}

GAEventMap

type GAEventMap = {
  [key: string]: GAEventFunction | GAEventMap;
};

Advanced Usage

Predefined Events

const gator = new GAtor({
  trackingId: 'G-XXXXXXXXXX',
  events: {
    buttonClick: () => ({
      category: 'UI',
      action: 'button_click',
      label: 'cta_button'
    }),
    formSubmit: () => ({
      category: 'Form',
      action: 'form_submit',
      label: 'contact_form'
    })
  }
});

// Use predefined events
gator.trackEvent(gator.events.buttonClick());

Generic Events

const gator = new GAtor({
  trackingId: 'G-XXXXXXXXXX',
  genericEvents: [
    {
      event: {
        category: 'User Interaction',
        action: 'page_interaction'
      },
      triggers: ['click', 'scroll', 'hover']
    }
  ]
});

// This will trigger both the original event and the generic event
gator.trackEvent({
  category: 'UI',
  action: 'click',
  label: 'navigation_menu'
});

Custom Parameters

gator.trackEvent({
  category: 'E-commerce',
  action: 'purchase',
  label: 'premium_plan',
  value: 99.99,
  currency: 'USD',
  transaction_id: 'txn_12345'
});

Error Handling

GAtor includes comprehensive error handling to ensure your application continues to work even if Google Analytics is unavailable:

• Initialization errors are caught and logged
• Event tracking errors are caught and logged
• Missing window object is handled gracefully
• All errors are logged to console for debugging

Browser Support

• Chrome 60+
• Firefox 55+
• Safari 12+
• Edge 79+

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

If you have any questions or need help, please open an issue on GitHub or contact us at [email protected].