@mifistix-cloud/analytics

Event Analytics SDK for Mifistix Cloud - Track user events and analytics data.

License

This module is licensed for internal use within Mifistix only. See LICENSE for details.

Installation

npm install @mifistix-cloud/analytics

Quick Start

const { initializeApp } = require('@mifistix-cloud/app');
const { getAnalytics, logEvent } = require('@mifistix-cloud/analytics');

// Initialize app first
const app = initializeApp({
  apiKey: 'your-api-key',
  projectId: 'your-project-id'
});

// Get analytics instance
const analytics = getAnalytics(app);

// Log an event
logEvent(analytics, 'button_click', {
  button_name: 'signup',
  screen: 'home'
});

// Set user properties
analytics.setUserProperties({
  plan: 'premium',
  region: 'eu'
});

// Set user ID
analytics.setUserId('user-123');

API Reference

getAnalytics(app)

Get analytics instance for an app.

Parameters:

• app (Object, required): Initialized app instance

Returns: Analytics client instance

Example:

const analytics = getAnalytics(app);

logEvent(analytics, eventName, params)

Log an analytics event.

Parameters:

• analytics (Object): Analytics instance
• eventName (string, required): Event name (validated)
• params (Object, optional): Event parameters

Example:

logEvent(analytics, 'purchase', {
  item_id: 'prod-123',
  price: 99.99,
  currency: 'USD'
});

setUserProperties(analytics, properties)

Set user properties that will be sent with all events.

Parameters:

• analytics (Object): Analytics instance
• properties (Object, required): User properties object

Example:

analytics.setUserProperties({
  subscription: 'premium',
  tier: 'gold'
});

setUserId(analytics, id)

Set user ID for event attribution.

Parameters:

• analytics (Object): Analytics instance
• id (string, required): User ID

Example:

analytics.setUserId('user-abc-123');

flushEvents(analytics)

Manually flush all queued events to server.

Parameters:

• analytics (Object): Analytics instance

Returns: Promise

Example:

await analytics.flushEvents();

stopAutoFlush()

Stop automatic event flushing (for testing).

Example:

analytics.stopAutoFlush();

Security Features

• Event Name Validation: Ensures event names are valid strings
• User ID Validation: Validates user ID before setting
• Error Handling: Logs warnings for invalid inputs without crashing
• Auto-flush: Automatically flushes events every 10 seconds
• Batch Processing: Sends events in batches of 50

Architecture

analytics/
├── src/
│   ├── core/
│   │   └── AnalyticsClient.js   # Main analytics client
│   ├── services/
│   │   └── EventQueue.js        # Event queue management
│   ├── utils/
│   │   └── helpers.js          # Helper functions
│   ├── types/
│   │   └── index.js            # Type definitions
│   └── config/
│       └── constants.js        # Configuration constants
└── index.js

Event Queue

Events are automatically queued and flushed in batches:

• Batch size: 50 events
• Auto-flush interval: 10 seconds
• Flush on page unload (browser)

License

MIT