Mailberry Tracker

Lightweight JavaScript library for tracking e-commerce events on your website. Sends data to Mailberry's tracking API for email marketing automation.

Installation

Add the script tag to your HTML with your Mailberry customer ID:

<script src="https://unpkg.com/@mailberry/[email protected]/build/tracker.min.js" data-customer-id="YOUR_CUSTOMER_ID"></script>

No build step needed. Works in any browser that supports fetch, localStorage, and sessionStorage.

Quick Start

<script src="https://unpkg.com/@mailberry/[email protected]/build/tracker.min.js" data-customer-id="YOUR_CUSTOMER_ID"></script>
<script>
  // 1. Identify the user (required before tracking)
  mailberry.identify({ email: '[email protected]' });

  // 2. Track events
  mailberry.item_viewed({
    product_id: 'prod-001',
    variant_id: 'var-blue-m',
    name: 'Blue Sneakers',
    image_url: 'https://store.example.com/img/blue.jpg',
    url: 'https://store.example.com/products/blue-sneakers',
    price: 89.99,
    currency: 'USD',
    vendor: 'NikeCo',
    sku: 'NK-BLU-42'
  });
</script>

API

mailberry.identify(identity)

Must be called before tracking events. Requires email. The customer_id is read automatically from the data-customer-id attribute on the script tag.

mailberry.identify({ email: '[email protected]' });

You can also pass customer_id directly to override the script attribute:

mailberry.identify({ customer_id: 'OVERRIDE_ID', email: '[email protected]' });

mailberry.item_viewed(params, customAttributes?)

Track a product view.

mailberry.item_viewed({
  product_id: 'prod-001',
  variant_id: 'var-blue-m',
  name: 'Blue Sneakers',
  image_url: 'https://store.example.com/img/blue.jpg',
  url: 'https://store.example.com/products/blue-sneakers',
  price: 89.99,
  currency: 'USD',
  vendor: 'NikeCo',
  sku: 'NK-BLU-42'
}, { source: 'homepage_carousel' });

Parameters: product_id, variant_id, name, image_url, url, price, currency, vendor, sku

mailberry.item_added_to_cart(params, customAttributes?)

Track an add-to-cart action.

mailberry.item_added_to_cart({
  cart_id: 'cart-789',
  product_id: 'prod-001',
  variant_id: 'var-blue-m',
  name: 'Blue Sneakers',
  image_url: 'https://store.example.com/img/blue.jpg',
  url: 'https://store.example.com/products/blue-sneakers',
  price: 89.99,
  currency: 'USD',
  quantity: 2,
  vendor: 'NikeCo',
  sku: 'NK-BLU-42'
});

Parameters: cart_id, product_id, variant_id, name, image_url, url, price, currency, quantity, vendor, sku

mailberry.checkout_start(params, customAttributes?)

Track checkout initiation.

mailberry.checkout_start({
  checkout_id: 'chk-123',
  checkout_token: null,
  cart_id: 'cart-789',
  checkout_url: 'https://store.example.com/checkout',
  value: 179.98,
  currency: 'USD',
  items: [
    { product_id: 'prod-001', variant_id: 'var-blue-m', name: 'Blue Sneakers',
      image_url: null, url: null, price: 89.99, currency: 'USD',
      quantity: 2, vendor: 'NikeCo', sku: 'NK-BLU-42', custom_attributes: {} }
  ]
});

Parameters: checkout_id, checkout_token, cart_id, checkout_url, value, currency, items

mailberry.checkout_cancel(params, customAttributes?)

Track checkout abandonment.

mailberry.checkout_cancel({
  checkout_id: 'chk-123',
  checkout_token: null,
  cart_id: 'cart-789',
  checkout_url: 'https://store.example.com/checkout',
  value: 179.98,
  currency: 'USD',
  reason: 'changed_mind',
  items: []
});

Parameters: checkout_id, checkout_token, cart_id, checkout_url, value, currency, reason, items

mailberry.checkout_complete(params, customAttributes?)

Track a completed purchase.

mailberry.checkout_complete({
  order_id: 'ord-456',
  checkout_id: 'chk-123',
  checkout_token: null,
  cart_id: 'cart-789',
  value: 179.98,
  currency: 'USD',
  items: [
    { product_id: 'prod-001', variant_id: 'var-blue-m', name: 'Blue Sneakers',
      image_url: null, url: null, price: 89.99, currency: 'USD',
      quantity: 2, vendor: 'NikeCo', sku: 'NK-BLU-42', custom_attributes: {} }
  ],
  shipping_address: { city: 'New York', state: 'NY', country: 'US' },
  billing_address: null,
  shipping_cost: 5.99,
  tax: 4.80,
  is_first_order: true,
  payment_method: 'credit_card'
}, { coupon: 'SUMMER10' });

Parameters: order_id, checkout_id, checkout_token, cart_id, value, currency, items, shipping_address, billing_address, shipping_cost, tax, is_first_order, payment_method

Custom Attributes

Every event method accepts an optional second argument for custom key-value data:

mailberry.item_viewed({ /* ... */ }, {
  color: 'blue',
  campaign: 'summer_sale',
  ab_variant: 'B'
});

Limits: max 20 keys, max 2KB total size. Exceeding limits triggers a console.warn.

Validation

Missing parameters trigger console.warn messages but do not block the event from being sent. Fields not provided are sent as null.

// This works but logs warnings for missing fields
mailberry.item_viewed({ name: 'Blue Sneakers', price: 89.99 });
// console: [Mailberry] item_viewed: missing "product_id"
// console: [Mailberry] item_viewed: missing "variant_id"
// ...

Typical Integration

<script src="https://unpkg.com/@mailberry/[email protected]/build/tracker.min.js" data-customer-id="YOUR_CUSTOMER_ID"></script>
<script>
  // On login / user identification
  function onUserLogin(email) {
    mailberry.identify({ email: email });
  }

  // On product page
  function onProductView(product) {
    mailberry.item_viewed({
      product_id: product.id,
      variant_id: product.variantId,
      name: product.name,
      image_url: product.imageUrl,
      url: window.location.href,
      price: product.price,
      currency: 'USD',
      vendor: product.vendor,
      sku: product.sku
    });
  }

  // On add to cart
  function onAddToCart(product, quantity) {
    mailberry.item_added_to_cart({
      cart_id: getCartId(),
      product_id: product.id,
      variant_id: product.variantId,
      name: product.name,
      image_url: product.imageUrl,
      url: window.location.href,
      price: product.price,
      currency: 'USD',
      quantity: quantity,
      vendor: product.vendor,
      sku: product.sku
    });
  }

  // On purchase complete
  function onPurchase(order) {
    mailberry.checkout_complete({
      order_id: order.id,
      checkout_id: order.checkoutId,
      checkout_token: null,
      cart_id: order.cartId,
      value: order.total,
      currency: order.currency,
      items: order.items,
      shipping_address: order.shippingAddress,
      billing_address: order.billingAddress,
      shipping_cost: order.shippingCost,
      tax: order.tax,
      is_first_order: order.isFirstOrder,
      payment_method: order.paymentMethod
    });
  }
</script>

How It Works

• Events are sent to Mailberry's public tracking API via fetch
• Failed requests retry with exponential backoff (up to 3 attempts)
• Permanently failed events are saved to localStorage and retried on next page load
• Session ID is generated per browser session via sessionStorage
• Context (page_url, referrer, user_agent, time) is collected automatically

Example

See example.html for a working demo with login/logout flow and all event types.

Support

Contact [email protected] or visit mailberry.ai.