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

``bash
npm install kewa-tracker-web
`

Usage

$3

`javascript
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: 'test@example.com',
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: 'test@example.com', // Required
});

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

$3

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

// Same API as above
`

$3

`html


`

API Reference

$3

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

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

$3

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

Example:
`javascript
// Send current page
await sendPageview();

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

$3

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

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

$3

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

Example:
`javascript
await setKewaContact({
email: 'test@example.com',
first_name: 'John',
last_name: 'Doe'
});
`

$3

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

Example:
`javascript
await resetKewaContact();
`

$3

Track app login event.

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

Returns: Promise

Example:
`javascript
await appLogin({
email: 'test@example.com', // Required
});
`

$3

Track app logout event.

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

Returns: Promise

Example:
`javascript
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:

`typescript
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;
declare function sendPageview(props?: PageviewProps): Promise;
declare function trackEvent(
event: string,
data?: Record,
contact?: any,
timestamp?: number
): Promise;
declare function setKewaContact(contact: any): Promise;
declare function resetKewaContact(): Promise;
declare function appLogin(contact: any, params?: any): Promise;
declare function appLogout(contact: any, params?: any): Promise;
`

Error Handling

The library provides helpful error messages:

`javascript
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