track()

The track() method records a custom event with a name and optional properties. Use it to capture user actions, conversions, and business events that matter to your analytics and marketing vendors.

Syntax

datafly.track(eventName, properties?)

Parameters

Returns

void

Basic usage

datafly.track('sign_up', { method: 'email' });

E-commerce example

datafly.track('purchase', {
  transaction_id: 'ORD-12345',
  value: 99.99,
  currency: 'USD',
  items: [
    { item_id: 'SKU-001', item_name: 'Running Shoes', price: 79.99, quantity: 1 },
    { item_id: 'SKU-042', item_name: 'Sport Socks', price: 9.99, quantity: 2 },
  ],
  coupon: 'SUMMER20',
  tax: 8.00,
  shipping: 5.99,
});

Standard e-commerce events

Datafly uses GA4-compatible event names. If you’re migrating from Google Tag Manager, your existing event names work as-is. Signal’s blueprints automatically map these to vendor-specific formats during server-side delivery.

Vendor mapping

When you use standard event names, Signal automatically maps them to vendor-specific events via blueprints:

Other standard events

Engagement

Authentication & leads

Custom events

You are not limited to standard event names. Track any event relevant to your business:

datafly.track('video_start', {
  video_id: 'vid-789',
  video_title: 'Product Demo',
  video_duration: 120,
});
 
datafly.track('outbound_click', {
  retailer_name: 'Amazon',
  link_url: 'https://amazon.co.uk/dp/B001234',
  click_type: 'product',
  item_id: 'SKU-001',
});
 
datafly.track('copy_voucher_code', {
  voucher_code: 'SAVE20',
  retailer_name: 'Nike',
  discount_type: 'percentage',
  discount_value: '20',
});

Custom events are delivered to vendors as custom/generic events and can be mapped to vendor-specific events using blueprint configuration.

Cross-platform deduplication with event_id

Pass an event_id property on conversion events to enable native deduplication against your existing vendor pixels (Meta Pixel, TikTok Pixel, Pinterest Tag, etc.). When the same event_id reaches a vendor via both their pixel and Signal’s server-side delivery, the vendor recognises them as the same event and counts it once.

datafly.track('purchase', {
  event_id: order.id,           // Same value as the Pixel's eventID parameter
  transaction_id: order.id,
  value: 99.99,
  currency: 'GBP',
});

On the corresponding pixel call, set the matching ID:

// Meta Pixel
fbq('track', 'Purchase', { value: 99.99, currency: 'GBP' }, { eventID: order.id });
 
// TikTok Pixel
ttq.track('PlaceAnOrder', { value: 99.99, currency: 'GBP', event_id: order.id });

The event_id property is promoted from properties to the top-level eventId envelope field before delivery. Customer’s event_id mappings in the integration blueprint take priority; the envelope value is used as a fallback.

Event payload

A track() call produces an event with type: "track":

{
  "type": "track",
  "event": "purchase",
  "anonymousId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "userId": "user-123",
  "properties": {
    "transaction_id": "ORD-12345",
    "value": 99.99,
    "currency": "GBP",
    "items": [
      { "item_id": "SKU-001", "item_name": "Running Shoes", "price": 79.99, "quantity": 1 }
    ]
  },
  "context": {
    "page": {
      "url": "https://example.com/checkout/confirmation",
      "path": "/checkout/confirmation",
      "referrer": "https://example.com/checkout/payment",
      "title": "Order Confirmation",
      "search": ""
    },
    "screen": { "width": 1920, "height": 1080 },
    "locale": "en-GB",
    "timezone": "Europe/London",
    "userAgent": "Mozilla/5.0 ...",
    "library": { "name": "@datafly/collector", "version": "0.1.0" }
  },
  "timestamp": "2026-02-25T14:22:00.000Z",
  "messageId": "df-b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e"
}

Batching

Events are not sent individually. Datafly.js batches up to 10 events per request and auto-flushes every 1 second. If 10 events accumulate before the flush interval, the batch is sent immediately.

Events are also flushed when the user navigates away from the page (via visibilitychange and pagehide listeners), using navigator.sendBeacon to ensure delivery survives page unload.

To force an immediate flush:

datafly.track('purchase', { transaction_id: 'ORD-12345', value: 99.99, currency: 'GBP' });
datafly.flush();

Property naming conventions

Use consistent, snake_case property names across your events:

• Use snake_case for property names (transaction_id, not orderId or TransactionId)
• Use GA4 standard property names when they exist (see the e-commerce table above)
• Include currency as an ISO 4217 code whenever you send monetary values
• Include value for conversion events to enable revenue attribution
• Use items[] for product arrays with item_id, item_name, price, quantity