Kewa Tracker Web

A JavaScript utility library to dynamically load tracking script from KEWA instance and track events with automatic page view tracking.

Features

• ✅ Dynamic Tracking script injection from KEWA instances
• ✅ Automatic page view tracking for SPAs (Single Page Applications)
• ✅ Custom event tracking
• ✅ Promise-based API
• ✅ TypeScript support
• ✅ Works with React, Vue, Angular, and vanilla JavaScript
• ✅ UMD and ESM module support

Installation

npm install kewa-tracker-web

Usage

ES6 Modules (Recommended)

import { initKewaTracker, sendPageview, trackEvent } from 'kewa-tracker-web';

// Initialize the tracker
await initKewaTracker({
  baseUrl: 'https://your-kewa-instance.com',
  projectId:'39r48kjbddkj', // Project Idenifier (optional)
  disableTracking: boolean, // Complteley disable tracking
  disablePageviewTracking: boolean, // Disable pageview tracking completely including manual pageview tracking
  disableEventTracking: boolean, // Disable event tracking
  customPageviewTracking: boolean, // Disable automatic pageview tracking and use manual pageview tracking by calling sendPageview()
});

// Send a custom pageview
await sendPageview({
  url: '/custom-page',
  title: 'Custom Page Title'
});

// Track custom events
await trackEvent('button_click', {
  button_id: 'header-cta',
  page: '/landing'
});

// Can be used to set the contact information for the current user.
// Example: You can set the contact information for the current user when the user logs in or registers.
await setKewaContact({
  email: '[email protected]',
  first_name: 'John',
  last_name: 'Doe'
});

// Reset the contact information for the current user.
// Example: You can reset the contact information for the current user when the user logs out.
await resetKewaContact();

// Track app login event.
await appLogin({
  email: '[email protected]', // Required
});

// Track app logout event.
await appLogout();

CommonJS

const { initKewaTracker, sendPageview, trackEvent, setKewaContact, resetKewaContact, appLogin, appLogout } = require('kewa-tracker-web');

// Same API as above

UMD (Browser)

<script src="https://unpkg.com/kewa-tracker-web/dist/kewa-tracking.umd.js"></script>
<script>
  // Available as global kewaTracking
  kewaTracking.initKewaTracker({
    baseUrl: 'https://your-kewa-instance.com',
    projectId: '39r48kjbddkj',
    disableTracking: false,
    disablePageviewTracking: false,
    disableEventTracking: false,
    customPageviewTracking: false
  }).then(() => {
    console.log('Tracker initialized!');
  });
</script>

API Reference

initKewaTracker(config)

Initialize the Kewa tracker with your KEWA instance configuration.

Parameters:

• config.baseUrl (string, required): The base URL of your KEWA instance
• config.projectId (string, optional): The project identifier
• config.disableTracking (boolean, optional): Completely disable tracking
• config.disablePageviewTracking (boolean, optional): Disable pageview tracking
• config.disableEventTracking (boolean, optional): Disable event tracking
• config.customPageviewTracking (boolean, optional): Disable automatic pageview tracking and use manual pageview tracking Returns: Promise<void>

Example:

await initKewaTracker({
  baseUrl: 'https://your-kewa-instance.com',
  projectId: '39r48kjbddkj', // Optional
  disableTracking: false,
  disablePageviewTracking: false,
  disableEventTracking: false,
  customPageviewTracking: false
});

sendPageview(props?)

Send a pageview event to track page visits.

Parameters:

• props (object, optional): Additional properties for the pageview
  • url (string): Custom URL to track
  • title (string): Page title
  • Any other custom properties

Returns: Promise<void>

Example:

// Send current page
await sendPageview();

// Send custom page
await sendPageview({
  url: '/custom-path',
  title: 'Custom Page'
});

trackEvent(event, data?, contact?, timestamp?)

Track custom events with optional data.

Parameters:

• event (string, required): Event name
• data (object, optional): Event data/properties
• contact (object, optional): Contact information
• timestamp (number, optional): Custom timestamp

Returns: Promise<void>

Example:

await trackEvent('purchase', {
  product_id: 'abc123',
  value: 29.99,
  currency: 'USD'
});

setKewaContact(contact)

Set the contact information for the current user. Example: You can set the contact information for the current user when the user logs in or registers.

Parameters:

• contact (object, required): Contact information

Returns: Promise<void>

Example:

await setKewaContact({
  email: '[email protected]',
  first_name: 'John',
  last_name: 'Doe'
});

resetKewaContact()

Reset the contact information for the current user. Example: You can reset the contact information for the current user when the user logs out.

Returns: Promise<void>

Example:

await resetKewaContact();

appLogin(contact, params?)

Track app login event.

Parameters:

• contact (object, required): Contact information
• params (object, optional): Additional parameters

Returns: Promise<void>

Example:

await appLogin({
  email: '[email protected]', // Required
});

appLogout(contact, params?)

Track app logout event.

Parameters:

• contact (object, optional): Contact information
• params (object, optional): Additional parameters

Returns: Promise<void>

Example:

await appLogout();

Automatic Page Tracking

The library automatically tracks page changes in Single Page Applications (SPAs) by listening to:

• history.pushState()
• history.replaceState()
• popstate events

This means you don't need to manually call sendPageview() for navigation in React Router, Vue Router, etc.

You can disable automatic page tracking by setting disablePageviewTracking to true in the initKewaTracker() function. d

TypeScript Support

The library includes TypeScript definitions:

interface KewaConfig {
  baseUrl: string;
  projectId: string;
  disableTracking?: boolean;
  disablePageviewTracking?: boolean;
  disableEventTracking?: boolean;
  customPageviewTracking?: boolean;
}

interface PageviewProps {
  url?: string;
  title?: string;
  [key: string]: any;
}

declare function initKewaTracker(config: KewaConfig): Promise<void>;
declare function sendPageview(props?: PageviewProps): Promise<void>;
declare function trackEvent(
  event: string,
  data?: Record<string, any>,
  contact?: any,
  timestamp?: number
): Promise<void>;
declare function setKewaContact(contact: any): Promise<void>;
declare function resetKewaContact(): Promise<void>;
declare function appLogin(contact: any, params?: any): Promise<void>;
declare function appLogout(contact: any, params?: any): Promise<void>;

Error Handling

The library provides helpful error messages:

try {
  await initKewaTracker({
    baseUrl: 'https://your-kewa-instance.com',
    projectId: '39r48kjbddkj', // Optional
  });
} catch (error) {
  console.error('Failed to initialize tracker:', error.message);
}

Browser Compatibility

• Modern browsers with ES2017+ support
• Internet Explorer 11+ (with polyfills)
• Node.js 14+

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License. See LICENSE file for details.

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions