Dream Shelter Analytics SDK

JavaScript/TypeScript SDK for tracking analytics events with comprehensive user data collection including geolocation, browser fingerprinting, IP detection, and session management.

Features

• 🎯 Event Tracking - Track custom events with properties
• 👤 User Identification - Identify users and track their properties
• 📄 Page View Tracking - Automatic page view tracking
• 🗺️ Geolocation - Browser GPS + IP-based geolocation
• 🔍 Browser Fingerprinting - Device, browser, OS detection
• 🌐 IP Detection - WebRTC + external services for public IP
• ⏱️ Session Management - Persistent sessions across page refreshes
• 🔑 API Key Validation - Secure authentication with backend
• 📊 Debug Mode - Comprehensive logging for development

Installation

npm install @dreamshelter/analytics-sdk

Quick Start

import DreamShelterAnalytics from '@dreamshelter/analytics-sdk';

// Initialize the SDK
const analytics = new DreamShelterAnalytics({
  apiKey: 'demo-api-key-12345',
  apiUrl: 'https://api.dreamshelter.org/analytics',
  debug: true, // Enable console logging
  trackSessionEnd: true, // Track session end on tab close
  trackLocation: false // Request location permission (optional)
});

// Track events
analytics.track('button_clicked', {
  button_name: 'donate',
  amount: 100
});

// Identify users
analytics.identify('user-123', {
  name: 'John Doe',
  email: '[email protected]'
});

// Track page views
analytics.page('Home Page', {
  section: 'landing'
});

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | required | Your API key from backend | | apiUrl | string | https://api.dreamshelter.org/analytics | Analytics API endpoint | | debug | boolean | false | Enable debug logging | | trackSessionEnd | boolean | true | Auto-track session end | | trackLocation | boolean | false | Request GPS location |

API Methods

track(eventName, properties)

Track a custom event with optional properties.

analytics.track('product_viewed', {
  product_id: 'SKU-12345',
  product_name: 'Winter Jacket',
  price: 99.99
});

identify(userId, userProperties)

Identify a user and set their properties.

analytics.identify('user-456', {
  name: 'Jane Smith',
  email: '[email protected]',
  plan: 'premium'
});

page(pageName, properties)

Track a page view.

analytics.page('Product Page', {
  category: 'clothing',
  product_id: 'SKU-12345'
});

reset()

Clear current user and start new session.

analytics.reset();

endSession()

Manually end the current session.

analytics.endSession();

requestLocation()

Manually request user's GPS location.

analytics.requestLocation()
  .then(location => {
    console.log('Location:', location);
  })
  .catch(error => {
    console.error('Location denied:', error);
  });

Data Collected

The SDK automatically collects:

Browser Fingerprint

• User agent, browser name/version
• Operating system and device type
• Screen resolution and color depth
• Language preferences
• Timezone and offset
• Device memory and CPU cores
• Cookie and DNT settings

Location Data

• GPS coordinates (if permission granted)
• IP-based geolocation (country, city, region)
• ISP and organization info

Session Data

• Unique session ID
• Session duration
• User ID (if identified)
• Page views and events

Network Data

• Public IP address
• Private/local IP (WebRTC)

Examples

E-Commerce Tracking

// Product viewed
analytics.track('product_viewed', {
  product_id: 'SKU-12345',
  category: 'Clothing',
  price: 99.99
});

// Add to cart
analytics.track('add_to_cart', {
  product_id: 'SKU-12345',
  quantity: 2
});

// Purchase
analytics.track('purchase_completed', {
  order_id: 'ORD-789',
  total_amount: 299.99
});

Donation Tracking (Dream Shelter)

analytics.track('donation_started', {
  amount: 100,
  currency: 'BDT',
  campaign: 'winter_shelter'
});

analytics.track('donation_completed', {
  donation_id: 'DON-456',
  amount: 100,
  payment_method: 'bkash'
});

Form Tracking

analytics.track('form_submitted', {
  form_name: 'contact_us',
  fields_completed: 5,
  success: true
});

Session Management

Sessions persist across page refreshes but end when:

• User closes tab/browser
• User calls analytics.reset()
• User calls analytics.endSession()

Session data is stored in localStorage with key dreamshelter_analytics_session.

API Key Setup

1. Get your API key from the backend admin panel
2. Use in SDK initialization:

const analytics = new DreamShelterAnalytics({
  apiKey: 'your-api-key-here'
});

The SDK validates the API key on initialization. Invalid keys prevent tracking.

Debug Mode

Enable debug mode to see detailed logs:

const analytics = new DreamShelterAnalytics({
  apiKey: 'demo-api-key-12345',
  debug: true // Shows all events, IP detection, geolocation, etc.
});

Console output includes:

• 🔑 API key validation
• 🔍 IP address detection (WebRTC + external services)
• 🗺️ Geolocation data
• 📊 All tracked events
• ✅ Success confirmations
• ❌ Error messages

TypeScript Support

The SDK is written in TypeScript and includes type definitions.

import DreamShelterAnalytics, {
  AnalyticsConfig,
  EventData,
  UserProperties
} from '@dreamshelter/analytics-sdk';

const config: AnalyticsConfig = {
  apiKey: 'demo-api-key-12345',
  debug: true
};

const analytics = new DreamShelterAnalytics(config);

Browser Support

• Chrome/Edge (latest 2 versions)
• Firefox (latest 2 versions)
• Safari (latest 2 versions)
• Opera (latest 2 versions)

Privacy

The SDK collects browser fingerprints and location data for analytics. Ensure you:

• Have proper privacy policy
• Get user consent where required (GDPR, etc.)
• Use trackLocation: false unless you need GPS data

Development

# Install dependencies
npm install

# Build the SDK
npm run build

# Run tests
npm test

# Start dev server
npm run dev

Custom Events

See CUSTOM_EVENTS.md for extensive examples of custom event tracking patterns.

License

MIT

Support

• GitHub: https://github.com/DreamShelterFoundation/analytics-sdk
• Issues: https://github.com/DreamShelterFoundation/analytics-sdk/issues

Changelog

1.0.0 (2025-10-01)

• Initial release
• Event tracking (track, identify, page)
• Browser fingerprinting
• IP detection (WebRTC + external services)
• Geolocation (GPS + IP-based)
• Session management with localStorage
• API key validation
• Debug mode with comprehensive logging