analytics-event-factory

analytics-event-factory is a lightweight and customizable library for standardizing analytics event creation and dispatch. It helps maintain a structured and consistent format for event metadata, making it easier to track user interactions and debug analytics pipelines.

🚀 Installation

npm install analytics-event-factory

💡 Features

• Flexible event creation system.
• Easily configurable event metadata and labels.
• Supports callback functions for custom event processing.
• Page and element-based event standardization.

📖 Usage Example

import { eventCreator } from "analytics-event-factory";

// Callback function to handle the event
function logEvent(eventMetadata) {
  console.log(
    "\n---------------EVENT LOG-----------------\n",
    JSON.stringify(eventMetadata, null, 2),
    "\n-------------END OF EVENT LOG-------------\n"
  );
}

// Create an event handler
const eventHandler = eventCreator({
  callback: logEvent,
  options: {
    page: {
      showOnLabel: true, // optional, default is false if not provided
      currentPage: "home", // optional, but only required if showOnLabel is true
      showOnMetadata: true, // optional, default is false if not provided
    },
    element: {
      showElementIdOnLabel: true, // optional, default is false if not provided
    },
  },
});

// Dispatching an event
eventHandler.button.click({
  id: "btn-1",
  timestamp: Date.now(),
  description: "Button clicked",
});

// Dispatching another event (without metadata)
eventHandler.button.click();

Expected Output

// return of the first event fired
{
  "label": "home.button.click.btn-1", // pattern: [page].[element-type].[action].[element-id]
  "metadata": {
    "elementId": "btn-1",
    "timestamp": 1739059943235,
    "description": "Button clicked",
    "page": "home",
  }
}

// return of the second event fired
{
  "label": "home.button.click", // pattern: [page].[element-type].[action]
  "metadata": {}
}

🔧 Configuration Options

The eventCreator function accepts two primary configuration objects:

callback

A function that will be executed whenever an event is dispatched.

options

An object to customize event behavior.

Option	Type	Description
page.showOnLabel	boolean?	Show the page name in the event label.
page.currentPage	string?	The current page name.
page.showOnMetadata	boolean?	Include the page name in the event metadata.
element.showElementIdOnLabel	boolean?	Show the element ID in the event label.

📚 API Reference

eventCreator({ callback, options })

Creates an event handler with the given callback and configuration options.

Parameters

• callback: A function to handle dispatched events.
• options: An object for configuration, as described in the table above.

Event Dispatch Methods

Each event handler provides functions to dispatch events by type (e.g., button.click). Event metadata can be passed as an argument.

Metadata Structure

{
  "label": "[page].[element-type].[action].[element-id]", // where page and element-id are optional
  "metadata": {
    "elementId": "[element-id]", // optional
    "page": "[page]" // optional
    // others metadata here
  }
}

🤝 Contributing

Feel free to open issues or submit pull requests if you find bugs or have suggestions for improvements.

📄 License

This project is licensed under the MIT License.