Mira Data Stream JavaScript SDK

A lightweight, flexible SDK for tracking events, page views, and user identities in web applications.

Installation

npm install mira-data-stream

Usage

Basic Usage

import { track, identify, page, setWriteKey } from 'mira-data-stream';

// Set your authentication write key (required)
// You can get this from the Mira Data Stream Producer API when creating a service
setWriteKey('your-write-key-here');

// Track an event
track('button_clicked', { 
  button_id: 'signup',
  page: 'landing' 
});

// Identify a user
identify('user123', {
  name: 'John Doe',
  email: '[email protected]'
});

// Track page view
page('home');

Advanced Usage

You can create a custom instance with specific configuration:

import { init } from 'mira-data-stream';

const analytics = init({
  apiUrl: 'https://api.example.com/tracking',
  writeKey: 'your-write-key-here', // Required for authentication
  flushInterval: 5000 // 5 seconds
});

// Use the custom instance
analytics.track('custom_event', {
  property1: 'value1',
  property2: 'value2'
});

Usage in React

import { useEffect } from 'react';
import { page, track, setWriteKey } from 'mira-data-stream';

function MyComponent() {
  useEffect(() => {
    // Set write key for authentication
    setWriteKey('your-write-key-here');
    
    // Track page view when component mounts
    page('my-component');
  }, []);

  const handleClick = () => {
    track('button_clicked', {
      component: 'MyComponent'
    });
  };

  return (
    <div>
      <h1>My Component</h1>
      <button onClick={handleClick}>Click Me</button>
    </div>
  );
}

API Reference

Functions

• track(eventName, properties, options) - Track an event
• identify(userId, traits) - Identify a user
• page(name, properties, options) - Track a page view
• setWriteKey(writeKey) - Set the write key for authentication with the server
• flush() - Manually flush the event queue
• reset() - Reset user identity
• init(options) - Initialize a new SDK instance with custom options

Options

• apiUrl - API URL for the Mira Data Stream Backend (default: 'http://localhost:8000/api/v1')
• userId - User ID for identifying the current user
• anonymousId - Anonymous ID for tracking non-logged-in users (auto-generated if not provided)
• writeKey - Write key for authentication with the server (required)
• flushInterval - Interval in milliseconds for flushing the event queue (default: 10000)

Authentication

The Mira Data Stream requires a write key for authentication. Each write key corresponds to a specific service in the backend.

To get a write key:

1. Create a service through the Mira Data Stream Producer API
2. Use the write key provided by the API in your SDK initialization

// Set the write key for authentication
setWriteKey('your-write-key-here');

// Or when initializing a new instance
const analytics = init({
  writeKey: 'your-write-key-here'
});

Browser Support

The SDK works in all modern browsers that support the Fetch API (Chrome, Firefox, Safari, Edge). For older browsers, you may need to include a polyfill for the Fetch API.

Development

If you want to contribute to this SDK, see the PUBLISHING.md file for development setup, testing, and publication instructions.

# Install dependencies
npm install

# Run tests
npm test

# Build the SDK
npm run build

License

MIT