Ewa Analytics Web SDK

A lightweight TypeScript SDK for tracking user events and analytics data in web applications. Provides real-time event tracking with support for both WebSocket and HTTP transport methods.

Endpoints and payload docs

Features

• Real-time Event Tracking: Track user interactions and custom events
• Session Management: Automatic session creation and tracking
• User Agent Parsing: Automatic device and browser detection
• Context Support: Add custom context to any event
• Transport Flexibility: Choose between WebSocket and HTTP
• TypeScript Support: Full type safety and IntelliSense
• Error Handling: Robust error handling and logging
• Debug Mode: Built-in debugging capabilities

Installation

npm install @2l/ewa-analytics-web-sdk
# or
yarn add @2l/ewa-analytics-web-sdk

Initialize

import { createEwaAnalyticsSdk } from '@2l/ewa-analytics-web-sdk';

const sdk = createEwaAnalyticsSdk();

await sdk.init({
  transport: 'http', // or 'websocket'
  apiUrl: 'https://your-api-endpoint.com',
  initData: {
    random_user_id: '4d1615ab-ee78-49aa-a10f-d57035322a41',
    platform: 'web',
    user_agent: navigator.userAgent,
    ip_address: '8.8.8.8'
  }
});

Required Fields

Learn more about payload fields

The initData object requires the following fields:

| Field | Type | Description | Example | |-------|------|-------------|---------| | random_user_id | String, UUIDv4 | Random user ID (per device per app, generate only once and keep) | 4d1615ab-ee78-49aa-a10f-d57035322a41 | ip_address | String | Device IP address | 8.8.8.8 | user_agent | String | Incoming raw user agent | Mozilla/5.0 (Linux; U; Android 4.4.2...)

Usage (Event Tracking)

sdk.trackEvent(eventType, payload, context);

eventType:

type EventType = 'session' | 'event'

payload - event payload that we need to pass manually for any event (example: event_subtype, event_value)

context - object that will be merged with payload and serialized according payload docs

ℹ️ Under the hood sdk takes responsibility for several event payload parametrs

• computed fields with user agent

language
timezone
os_version
os_name
device_name
device_type

• event_id always new uuid()
• event_value - ment to pass extra paramentr for analytics as JSON stringified object. Has predermined required values (will be generated from userAgent from initData)

  browser
  browser_version

• clear falsy fields

Transport

The SDK supports two transport methods:

• WebSocket: Real-time bidirectional communication (do not use for now)
• HTTP: Traditional REST API calls

Configure transport during initialization:

// WebSocket transport
await sdk.init({
  transport: 'websocket',
  // ... other config
});

// HTTP transport
await sdk.init({
  transport: 'http',
  // ... other config
});

Internal Events

The SDK automatically sends internal events:

• Session Started: Sent when SDK initializes
• Session Located: Sent when location data is available
• Client Attribution: Sent for fingerprinting and attribution

How it works

🔧 Initialization Phase

1. SDK Creation → Creates internal state management
2. Config Validation → Checks required fields (transport, apiUrl, randomUserId)
3. Transport Setup → Initializes HTTP client or WebSocket connection
4. Event Handlers → Sets up EventTracker and InternalEvents

🤖 Internal Events Phase (under the hood)

1. Auto Internal Events Check → Determines if automatic sending is enabled
2. Session Started → Basic session initialization event
3. Session Located → Location-based session event (requires country/IP)

📝 Event Tracking Phase

1. Event Type Determination → Session vs Analytics event routing
2. Session State Validation → Ensures session is located and initial events sent
3. Payload Processing → Merges context, user agent, and session data
4. Serialization → Converts to proper payload format with fingerprinting and payload fields according to docs

Scheme