Retention Tracker Web

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

Features

• ✅ Dynamic Tracking script injection from retention 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 retention-tracker-web

Usage

ES6 Modules (Recommended)

import { initRetentionTracker, sendPageview, trackEvent } from 'retention-tracker-web';

// Initialize the tracker
await initRetentionTracker({
  baseUrl: 'https://your-retention-instance.com'
});

// 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'
});

CommonJS

const { initRetentionTracker, sendPageview, trackEvent } = require('retention-tracker-web');

// Same API as above

UMD (Browser)

<script src="https://unpkg.com/retention-tracker-web/dist/retention-tracking.umd.js"></script>
<script>
  // Available as global retentionTracking
  retentionTracking.initRetentionTracker({
    baseUrl: 'https://your-retention-instance.com'
  }).then(() => {
    console.log('Tracker initialized!');
  });
</script>

API Reference

initRetentionTracker(config)

Initialize the Retention tracker with your retention instance configuration.

Parameters:

• config.baseUrl (string, required): The base URL of your retention instance

Returns: Promise<void>

Example:

await initRetentionTracker({
  baseUrl: 'https://your-retention-instance.com'
});

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'
});

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.

TypeScript Support

The library includes TypeScript definitions:

interface RetentionConfig {
  baseUrl: string;
}

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

declare function initRetentionTracker(config: RetentionConfig): Promise<void>;
declare function sendPageview(props?: PageviewProps): Promise<void>;
declare function trackEvent(
  event: string,
  data?: Record<string, any>,
  contact?: any,
  timestamp?: number
): Promise<void>;

Error Handling

The library provides helpful error messages:

try {
  await initRetentionTracker({
    baseUrl: 'https://your-retention-instance.com'
  });
} 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