Events SDK

A lightweight SDK for tracking events and user behavior in your application.

🚀 Installation

npm install @jamesbond007db05/events-sdk

⚡ Setup

Initialize the SDK once when your app starts:

import { initTracker } from '@jamesbond007db05/events-sdk';

const tracker = initTracker({
  apiKey: 'your_api_key_here',
  autoPage: true
});

⚙️ Configuration

Pass options directly to initTracker:

initTracker({
  apiKey: 'your_api_key',
  autoPage: true,
  batchSize: 20,
  flushIntervalMs: 5000
});

Options

• apiKey (required) – Your API key
• batchSize – Number of events per batch
• flushIntervalMs – Flush interval in milliseconds
• sampleRate – Control event sampling
• autoPage – Automatically track page views
• debug – Enable debug logging
• maxRetries – Retry attempts for failed requests
• requestTimeoutMs – Network timeout duration
• maxEventBytes – Max size of a single event
• maxBatchBytes – Max size of a batch
• storageKey – Storage key for persistence

📊 Usage

Track an event

await tracker.track('button_clicked', {
  label: 'signup'
});

Identify a user

await tracker.identify('user_123', {
  email: '[email protected]'
});

Link anonymous user to logged-in user

await tracker.alias('anon_id', 'user_123');

Track page view manually

await tracker.page({
  title: 'Pricing'
});

Track event with user

await tracker.trackWithUser('user_123', 'purchase_completed', {
  amount: 199
});

Send events immediately

await tracker.flush();

🧠 Access existing tracker

import { getTracker } from '@jamesbond007db05/events-sdk';

const tracker = getTracker();

🎨 In-App Engagement Runtime (Guides, Surveys & Checklists)

The SDK includes a powerful in-app engagement engine (Engagement) that automatically fetches, evaluates, and renders targeted user experiences (such as modals, surveys, hotspots, and checklists) based on real-time event triggers and URL targeting.

Setup & Initialization

Initialize the Engagement runtime once at the entry point of your application:

import { Engagement } from '@jamesbond007db05/events-sdk';

Engagement.init({
  apiKey: 'your_api_key_here',
  tenantId: 'your_tenant_id_here',
  userId: 'user_123', // Optional: for user targeting
  sessionId: 'session_abc', // Optional: session identifier
  debug: true // Optional: enables debug logs in development
});

Supported In-App Experiences

The SDK runtime dynamically evaluates targeting rules and delivers:

• Modals (Guides): Premium popups for announcements, promotions, or feature introductions.
• NPS & Rating Surveys: Custom feedback dialogs (NPS scales, stars, emojis, multiple choice, text inputs) that automatically sync responses with the backend.
• Checklists: Dynamic on-screen widgets to track onboarding progress and user achievements.
• Hotspots: Interactive highlighted points pointing to specific DOM elements.

API Reference

• Engagement.init(config) – Set up and start the runtime. Installs history-based route monitoring and loads styling.
• Engagement.refresh() – Manually force evaluation and synchronization of targeted experiences.
• Engagement.getCurrentExperiences() – Returns an array of currently active experiences.
• Engagement.destroy() – Tear down all active DOM elements, listeners, and observers.

🧪 Utilities

Validate API key

import { validateApiKeyFormat } from '@jamesbond007db05/events-sdk';

Validate payload

import { validatePayload } from '@jamesbond007db05/events-sdk';

Normalize errors

import { normalizeSdkError } from '@jamesbond007db05/events-sdk';

🌐 Environment

• Modern browsers
• Node.js 18+

🚀 Release

npm version patch
git push origin --tags

📄 License

MIT