Event Specs

Datafly Signal uses a consistent set of snake_case event IDs across all verticals. These IDs are:

• The value sent in the event field by Datafly.js (e.g. datafly.track('add_to_cart', {...}))
• The key used in your pipeline’s Per-Event Parameters configuration
• The stable identifier used for vendor event name mapping

How event IDs work

Every event flowing through Signal has an event field:

{
  "type": "track",
  "event": "add_to_cart",
  "properties": {
    "currency": "GBP",
    "value": 79.99,
    "items": [
      { "item_id": "SKU-001", "item_name": "Running Shoes", "price": 79.99, "quantity": 1 }
    ]
  }
}

The pipeline engine looks up the event value against your Per-Event Parameters configuration. If a matching section exists, those field mappings are applied on top of the global parameters before delivery to the vendor.

Built-in events

These events are sent automatically by Datafly.js without any track() call:

Classifying page views with page_type

page is vertical-neutral and fires on every page load, so on its own it says nothing about what kind of page was viewed. Several destinations model page views by type rather than as one undifferentiated event, and can only report properly when they know which.

Pass an optional page_type to classify it:

datafly.page({ page_type: 'content' })

Destinations that don’t model page types ignore it. Destinations that do fall back to their generic page type when it’s absent or unrecognised, so adding it can only improve fidelity, never break a working integration.

Common events

These optional events apply across any vertical. They’re documented here so they map consistently across destinations.

consent

Fired when a user grants or withdraws consent for a communications channel or purpose: a newsletter opt-in, an SMS marketing checkbox, a preference-centre change, an unsubscribe.

datafly.track('consent', {
  consent_category: 'weekly_newsletter',        // your own category identifier
  consent_action: 'granted',                    // 'granted' | 'denied'
  consent_message: 'Send me weekly offers',     // what the user actually saw
  consent_valid_until: 'unlimited'              // optional; 'unlimited' or a timestamp
})

The event timestamp is the moment consent was given, and destinations treat it as the consent’s valid_from. Fire this event on change only, never on every page load: repeating a grant floods the profile and destroys the audit trail’s meaning.

Because this event carries a permission decision rather than behavioural data, destinations that accept it may receive it even where the cookie-consent gate would otherwise close, but only where an operator has explicitly configured that destination to accept consent from Signal. It is off by default everywhere.

Vertical specs

Choose the spec that matches your business model. You can mix events from multiple verticals — a subscription news site might use both Publishing and SaaS events.

Property conventions

All event properties use snake_case:

// Correct
datafly.track('purchase', {
  transaction_id: 'ORD-1234',
  value: 129.99,
  currency: 'GBP',
  items: [{ item_id: 'SKU-001', item_name: 'Trainers', price: 79.99, quantity: 1 }],
});
 
// Avoid
datafly.track('purchase', {
  transactionId: 'ORD-1234',   // camelCase — avoid
  Value: 129.99,               // PascalCase — avoid
});

Standard monetary properties: