Analytics-event-factory NPM

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
  }
}