@2l/ewa-analytics-web-sdk/README.md

# 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](https://lithiumlab.atlassian.net/wiki/spaces/EWA/pages/3839524867/D-Stream)

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

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

## Initialize

```typescript
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](https://lithiumlab.atlassian.net/wiki/spaces/EWA/pages/3839524867/D-Stream)

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)
```typescript
sdk.trackEvent(eventType, payload, context);
```
`eventType`:
```typescript 
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. <br>
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:

```typescript
// 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](https://lithiumlab.atlassian.net/wiki/spaces/EWA/pages/3839524867/D-Stream)


### Scheme
<details> 
  <p >
    <img src="./main-scheme.png" alt="App preview" width="400"/>
  </p>