@kgen-events

@kgen-events is a browser-side analytics helper for KGeN web apps. It tracks custom events, automatically manages analytics sessions, enriches events with device and channel information, sends data to Firebase Analytics, and also calls a tracker endpoint with the same event payload.

package.json currently publishes this package as track-event-analytics, so use that package name when installing or importing it.

What It Does

• Exposes a default event tracking function.
• Starts a new analytics session automatically when needed.
• Emits session events such as analytic_SessionStart, analytic_SessionEnd, and first_page_load.
• Detects channel automatically as website or mweb.
• Adds browser and OS metadata for session lifecycle events.
• Sends events to both Firebase Analytics and a tracker URL.
• Supports both Next.js-style NEXT_PUBLIC_* env vars and Vite-style VITE_API_* env vars.

Installation

npm install track-event-analytics

Usage

import trackAnalytics from "track-event-analytics";

trackAnalytics("Homepage_shown", {
  userId: "user-123",
  entryPoint: "/",
});

trackAnalytics("click_ContinuewithGoogle", {
  userId: "user-123",
  loginSessionId: "login-session-1",
  entryPoint: "/login",
});

The package exports a default function:

trackAnalytics(eventName, eventAttributes);

Event Payload

You can pass any of the supported analytics fields as the second argument. Common fields include:

• userId
• loginSessionId
• entryPoint
• campaignId
• taskId
• social
• failureReason
• walletId
• pageType
• scrollDepth
• timeSpent

Null and undefined values are filtered out before events are sent.

Environment Variables

Configure Firebase and tracker settings in your app environment:

# Firebase
NEXT_PUBLIC_FIREBASE_API_KEY=""
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=""
NEXT_PUBLIC_FIREBASE_PROJECT_ID=""
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=""
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=""
NEXT_PUBLIC_FIREBASE_APP_ID=""
NEXT_PUBLIC_FIREBASE_MEASUREMENT_ID=""

# Runtime
NEXT_PUBLIC_ENVIRONMENT="Staging"
NEXT_PUBLIC_GAME_ID=""
GAME_ACCOUNT_ID=""
NEXT_PUBLIC_BASE_URL_TRACKER=""

Vite equivalents are also supported:

VITE_API_FIREBASE_API_KEY=""
VITE_API_FIREBASE_AUTH_DOMAIN=""
VITE_API_FIREBASE_PROJECT_ID=""
VITE_API_FIREBASE_STORAGE_BUCKET=""
VITE_API_FIREBASE_MESSAGING_SENDER_ID=""
VITE_API_FIREBASE_APP_ID=""
VITE_API_FIREBASE_MEASUREMENT_ID=""
VITE_API_ENVIRONMENT="Staging"
VITE_API_GAME_ID=""
VITE_API_GAME_ACCOUNT_ID=""
VITE_API_BASE_URL_TRACKER=""

Behavior Notes

• This package is intended for browser usage. It relies on APIs such as window, navigator, and localStorage.
• On the first tracked event of a session, the library can automatically emit analytic_SessionStart and first_page_load.
• A session is treated as inactive after 30 minutes without events.
• Event names must exist in the package's internal event ID map for the current environment, otherwise the event is skipped with an error log.
• The entryPoint value / is normalized to Home_Page.

Development

npm run build

The build output is generated in dist/.