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

_df.track(eventName, properties?)

Parameters

Returns

void

Basic usage

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

E-commerce example

_df.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:

_df.track('video_start', {
  video_id: 'vid-789',
  video_title: 'Product Demo',
  video_duration: 120,
});
 
_df.track('outbound_click', {
  retailer_name: 'Amazon',
  link_url: 'https://amazon.co.uk/dp/B001234',
  click_type: 'product',
  item_id: 'SKU-001',
});
 
_df.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.

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:

_df.track('purchase', { transaction_id: 'ORD-12345', value: 99.99, currency: 'GBP' });
_df.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