EDTS Beacon Analytics Library

The EDTS Beacon Analytics Library is a JavaScript SDK written in TypeScript, intended to be used by websites wishing to send semantic telemetry, analytics, and tracking data to the Beacon backend.

⚠️ Beta Notice

This library is currently in beta testing phase.
APIs may change, and some features may not be fully stable yet.
It is recommended for testing and early integration purposes only.

📦 Installation

Install via NPM:

npm install --save @edts/beacon-analytics

🚀 Quick Start

1. Initialize the SDK

Import the module into your application and initialize it using your assigned API Key:

import * as beacon from '@edts/beacon-analytics';

beacon.init("YOUR_BEACON_API_KEY", {
    appVersion: "1.0.0", // current app version
    userId: "user-id-123", // current logged in user ID
});

Initialization Configuration Options

| Name | Description | Default | |----------------------|-----------------------------------------------------------------------------|----------------------| | apiKey | Required The API key for your analytics project. Required to authenticate and send data to the analytics backend. | - | | appVersion | Version number of the application, useful for segmenting analytics data by app version. | - | | flushIntervalMillis| Time interval (in milliseconds) at which queued events are automatically sent to the server. | 1000 (1 second) | | flushQueueSize | The number of events to queue before automatically sending them to the server. | 30 | | sessionId | Unique ID for the current session. Used to group events into a single session in analytics. | Generated per session| | sessionTimeout | The duration (in milliseconds) of inactivity — measured from the last event trigger while the app is in the background — after which a new session ID will be generated upon the next event trigger. | 1800000 (30 mins) | | userId | Unique identifier for the user. Helps track the same user across devices and sessions. | - | | baseUrl | Required URL destination for tracked event payloads. | - |

2. Track an Event

You can track an event anywhere in your app by providing the Event Group, the Event Name, and any custom properties.

// Generic tracking format:
// beacon.track("EVENT_GROUP", "EVENT_NAME", eventProperties, userProperties);

const eventProperties = { previous_tier: "Blue", new_tier: "Silver", poin_required: "10000" };
const userProperties = { tier: "Silver", poin: "20" };

beacon.track("CLICK", "Button Clicked", eventProperties, userProperties);

Event Groups

Developers must include the EVENT_GROUP code as the first parameter of beacon.track(), strictly corresponding to the Event Group configured in the Sentinel Web application.

For example, if the "Add to Cart" event is configured with the Event Group "Event Submission" in Web Sentinel, you must send the string code EVENT_SUBMISSION as the first argument.

The valid Event Group parameters are:

• Click: CLICK
• Page View: PAGE_VIEW
• Event Submission: EVENT_SUBMISSION
• App Activity: APP_ACTIVITY
• User Impression: USER_IMPRESSION

📄 License

Proprietary — EDTS Internal Use