npm package: @mailberry/tracker
Description: Client-side event tracking script for Mailberry
Author: Mailberry
Latest version: 0.0.2

# Mailberry Tracker

Mailberry Tracker is a lightweight JavaScript library for tracking user interactions and events on your website. It sends data to Mailberry's backend for processing and analysis.

## Installation

Add the Mailberry tracker script to your HTML document:

```html
<script defer id="mailberry-tracker" src="https://unpkg.com/mailberry-tracker@0.0.2/build/tracker.min.js" data-customer-id="YOUR_CUSTOMER_ID"></script>
```

Replace `YOUR_CUSTOMER_ID` with the ID provided by Mailberry.

## Usage

### Identifying Users

Before tracking events, you should identify the current user:

```javascript
mailberry.identify({
  email: 'user@example.com',
  firstName: 'John',
  lastName: 'Doe',
  // Add any other user attributes
});
```

The identify method returns a Promise, so you can chain actions:

```javascript
mailberry.identify({ email: 'user@example.com' }).then(() => {
  // Continue with tracking events
});
```

### Tracking Events

Use the `track` method to record user interactions:

```javascript
mailberry.track('purchase', {
  productId: 'prod-123',
  price: 99.99,
  currency: 'USD'
});
```

The first parameter is the event type (e.g., 'purchase', 'click', 'pageview'), and the second is an object containing event data.

### Using the Push Method

The `push` method allows you to queue commands for execution:

```javascript
mailberry.push(['track', 'Started Checkout', { cartValue: 150 }]);
```

Push accepts an array with the following format:
- First element: command name ('track' or 'identify')
- Second element: event type (for 'track') or user info (for 'identify')
- Third element: event data (for 'track') or callback function (for 'identify')

### Examples

#### Basic Page View Tracking

```javascript
document.addEventListener('DOMContentLoaded', function() {
  mailberry.identify({ email: 'user@example.com' }).then(() => {
    mailberry.track('pageview', { page: window.location.pathname });
  });
});
```

#### E-commerce Purchase Tracking

```javascript
function trackPurchase(orderId, items, total) {
  mailberry.track('purchase', {
    orderId: orderId,
    items: items,
    totalAmount: total,
    currency: 'USD',
    timestamp: new Date().toISOString()
  });
}
```

#### Form Submission Tracking

```javascript
document.getElementById('contact-form').addEventListener('submit', function() {
  mailberry.track('form_submit', {
    formId: 'contact-form',
    formName: 'Contact Us'
  });
});
```

## Advanced Configuration

### Error Handling

All methods return Promises, so you can handle errors:

```javascript
mailberry.track('event', data)
  .then(response => {
    console.log('Event tracked successfully');
  })
  .catch(error => {
    console.error('Error tracking event:', error);
  });
```

### Automatic Retries

The tracker automatically saves failed events to localStorage and retries sending them when possible.

## Browser Compatibility

Mailberry Tracker works in all modern browsers that support:
- Promises
- localStorage
- XMLHttpRequest

## Support

For support, please contact support@mailberry.com or visit [our documentation](https://docs.mailberry.com).