Sunbird Telemetry SDK (v2.x.x)

A robust, isomorphic JavaScript/TypeScript library for generating and syncing Sunbird telemetry events. This version is a complete rewrite using modern TypeScript, replacing legacy dependencies with standard NPM packages.

Features

• Isomorphic Support: Works seamlessly in both Browser and Node.js environments.
• Modern Stack: Written in TypeScript with ES6+ features.
• Dependency Optimization: Replaced jquery, fingerprintjs2, md5 with:
  • Native fetch API (no jQuery dependency).
  • @fingerprintjs/fingerprintjs for browser fingerprinting.
  • crypto-js for hashing.
  • ajv for schema validation.
  • ua-parser-js for user agent parsing.
• Sticky Fingerprint: Implements localStorage caching to ensure consistent device IDs across browser sessions.
• Type Safety: Full TypeScript definitions included.
• Multiple Builds: CommonJS (CJS), ES Modules (ESM), and Browser Global (IIFE).

Installation

npm install @project-sunbird/telemetry-sdk

Usage

Browser (ES Modules / Bundlers)

import { $t } from '@project-sunbird/telemetry-sdk';

$t.initialize({
    pdata: { id: 'my-app', ver: '1.0', pid: 'sunbird-portal' },
    env: 'home',
    channel: 'in.ekstep',
    did: 'device-id', // Optional: Library will auto-generate if missing
    authtoken: 'your-auth-token',
    host: 'https://api.sunbird.org',
    endpoint: '/v1/telemetry'
});

$t.start(
    {}, // Config overrides
    'content-id',
    '1.0',
    { type: 'app', mode: 'play', pageid: 'home' }
);

$t.interact({
    type: 'CLICK',
    id: 'play-button',
    pageid: 'home'
});

Browser (Script Tag)

The library exposes a global Telemetry object. It also aliases window.$t and window.EkTelemetry for backward compatibility.

<script src="path/to/dist/index.global.js"></script>
<script>
    $t.initialize({ ... });
    $t.start(...);
</script>

Node.js

const { $t } = require('@project-sunbird/telemetry-sdk');

// Note: In Node.js, you should ideally provide a 'did' (Device ID)
// or 'uid' (User ID) as fingerprinting relies on browser features.
$t.initialize({
    pdata: { id: 'my-service', ver: '1.0' },
    env: 'backend',
    channel: 'in.ekstep',
    host: 'https://api.sunbird.org',
    batchsize: 10
});

$t.log({
    type: 'api_access',
    level: 'INFO',
    message: 'API Request Received',
    params: [{ url: '/api/v1/user' }]
});

Configuration

| Property | Description | Default | | --- | --- | --- | | pdata | Producer Data (Required) | { id: "in.ekstep", ver: "1.0" } | | env | Environment (Required) | "contentplayer" | | channel | Channel ID (Required) | "in.ekstep" | | did | Device ID | Browser fingerprint or UUID (Node) | | uid | User ID | "anonymous" | | sid | Session ID | "" | | batchsize | Number of events to batch before syncing | 20 (Max 1000) | | host | API Host URL | https://api.ekstep.in | | endpoint | API Endpoint | /data/v3/telemetry | | authtoken | Authorization Token | "" | | enableValidation| Validate events against schema | false | | dispatcher | Custom dispatcher object { dispatch: (event) => {} } | undefined |

Note on Validation: If enableValidation is set to true, the library validates events against the built-in Telemetry V3 schema. Events with missing or invalid schemas will be dropped.

Development

Scripts

• npm run build: Build the library using tsup (generates dist/).
• npm run lint: Lint source code using eslint.
• npm test: Run unit tests using vitest.

Project Structure

• src/core: Core telemetry logic (Telemetry, TelemetrySyncManager).
• src/services: Services like DeviceService (fingerprinting) and Validator (schema).
• src/utils: Utilities (Dispatcher, Utils, DeviceInfo).
• src/schema: Telemetry JSON schemas.

Migration from v1.x

1. Remove jQuery: Ensure your application handles network requests if you were relying on the SDK's jQuery dependency. The SDK now uses fetch.
2. Fingerprinting: The library now uses @fingerprintjs/fingerprintjs. This might generate different device IDs than the old library. However, localStorage caching is implemented to maintain the ID once generated.
3. Imports: If using ES modules, import { $t } or { Telemetry } instead of relying on globals.