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('Button Clicked', { label: 'Sign Up' });

E-commerce example

_df.track('Order Completed', {
  orderId: '12345',
  revenue: 99.99,
  currency: 'USD',
  products: [
    { id: 'SKU-001', name: 'Running Shoes', price: 79.99, quantity: 1 },
    { id: 'SKU-042', name: 'Sport Socks', price: 9.99, quantity: 2 },
  ],
  coupon: 'SUMMER20',
  tax: 8.00,
  shipping: 5.99,
});

Standard e-commerce events

Datafly recognises the following standard event names and maps them automatically to vendor-specific events during server-side delivery. You can use any event name you like, but using these standard names enables automatic mapping without additional pipeline configuration.

Vendor mapping

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

Lead generation events

Custom events

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

_df.track('Video Played', {
  videoId: 'vid-789',
  title: 'Product Demo',
  duration: 120,
  percentWatched: 50,
});
 
_df.track('Search Performed', {
  query: 'running shoes',
  resultsCount: 42,
  filters: { brand: 'nike', size: '10' },
});
 
_df.track('Subscription Upgraded', {
  previousPlan: 'starter',
  newPlan: 'professional',
  mrr: 99,
});

Custom events are delivered to vendors as custom/generic events and can be mapped to vendor-specific events using pipeline transformation rules.

Event payload

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

{
  "type": "track",
  "event": "Order Completed",
  "anonymousId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "userId": "user-123",
  "properties": {
    "orderId": "12345",
    "revenue": 99.99,
    "currency": "USD"
  },
  "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-US",
    "timezone": "America/New_York",
    "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('Order Completed', { orderId: '12345', revenue: 99.99 });
_df.flush();

Property naming conventions

Use consistent property names across your events for easier reporting and vendor mapping:

• Use camelCase for property names (orderId, not order_id or OrderId)
• Use 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 revenue or value for conversion events to enable revenue attribution