Track

Explaining the track events, properties and the methods to propagate to destinations

The Track API records user actions (events) along with their associated properties. It is designed to capture and propagate information to specified destinations in a structured manner.

Each action is called an event. Each event has a name and some properties associated with it along with an optional callback function. For example, the event name could be productViewed, while the properties can be sort, currency etc.

Example:

Sample JavaScript track event call: 
lmSMTObj.track("productViewed", {
    "currency": "INR",
    "filters": "Price < 5000",
    "sort": "Price (Low to High)",
    "product": {
        "name": "Earbuds",
        "category": "Mobile Phone & Accessories",
        "position": 1
    }
}, {
    "trackerId": "6791c47a-0178-47bc-8711-86a2c67b2255"
}, function() {})
Sample track event payload:
{
  "id": "viz_6139c51ee9662",
  "userId": "6791c47a-0178-47bc-8711-86a2c67b2255",
  "otherIds": {
    "_fbp": 1631176031249,
    "_fbc": "6791c47a-0178-47bc-8711-86a2c67b2255",
    "_ga": "1631176031249",
    "trackerId" : "6791c47a-0178-47bc-8711-86a2c67b2255"
  },
  "context": {
    "library": {
      "name": "javascript",
      "version": "0.01"
    },
    "page": {
      "path": "/academy/",
      "referrer": "",
      "search": "",
      "title": "Analytics Academy",
      "url": "https://hcl.cdp.co"
    },
    "userAgent": {
      "deviceType": "DESKTOP",
      "osType": "Linux",
      "osVersion": "Linux",
      "browser": "Chrome",
      "ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/46.0.2490.86 Safari/537.36"
    },
    "ip": "108.0.78.21",
    "utm": {
      "campaign": "TPS Innovation Newsletter",
      "source": "Newsletter",
      "medium": "email",
      "term": "tps reports",
      "content": "image link"
    }
  },
  "event": "productViewed",
  "messageId": "ajs-f8ca1e4de5024d9430b3928bd8ac6b96",
  "properties": {
  "currency": "INR",
  "filters": "Price < 5000",
  "sort": "Price (Low to High)",
  "product": {
    "name": "Earbuds",
    "category": "Mobile Phone & Accessories",
    "position": 1
  }
},
  "receivedAt": "2015-12-12T19:11:01.266Z",
  "sentAt": "2015-12-12T19:11:01.169Z",
  "timestamp": "2015-12-12T19:11:01.249Z",
  "type": "track",
  "originalTimestamp": "2015-12-12T19:11:01.152Z",
  "writeKey": "aUL2rZghe5jHvjWh"
}

Event

An event represents a single action performed by the user. Each event must have a name and may include associated properties.

Naming Conventions: Use camelCase for event names, ensuring clarity and semantic accuracy (e.g., productSearched, registerButtonClicked). Avoid generic names like event123 or rBClk.

Properties

Properties provide additional context for an event, such as user details, action specifics, or product metadata.

Structure: Properties are passed as a JSON object in the track event call.

Supported Data Types: String, Number, Boolean, and Object (hash).

Example:

In the event productViewed, the properties include:

{
  "currency": "INR",
  "filters": "Price < 5000",
  "sort": "Price (Low to High)",
  "product": {
    "name": "Earbuds",
    "category": "Mobile Phone & Accessories",
    "position": 1
  }
}

Track API Call

Track API Call

The Track API call records events, their properties, and includes optional callbacks.

JavaScript Example:
lmSMTObj.track("productViewed", {
    "currency": "INR",
    "filters": "Price < 5000",
    "sort": "Price (Low to High)",
    "product": {
        "name": "Earbuds",
        "category": "Mobile Phone & Accessories",
        "position": 1
    }
}, {
    "trackerId": "6791c47a-0178-47bc-8711-86a2c67b2255"
}, function() {})

Track Event Payload

A typical track event payload includes metadata about the event and its context.

Sample Payload:
{
  "id": "viz_6139c51ee9662",
  "userId": "6791c47a-0178-47bc-8711-86a2c67b2255",
  "otherIds": {
    "_fbp": 1631176031249,
    "_fbc": "6791c47a-0178-47bc-8711-86a2c67b2255",
    "_ga": "1631176031249",
    "trackerId": "6791c47a-0178-47bc-8711-86a2c67b2255"
  },
  "context": {
    "library": {
      "name": "javascript",
      "version": "0.01"
    },
    "page": {
      "path": "/academy/",
      "referrer": "",
      "search": "",
      "title": "Analytics Academy",
      "url": "https://hcl.cdp.co"
    },
    "userAgent": {
      "deviceType": "DESKTOP",
      "osType": "Linux",
      "osVersion": "Linux",
      "browser": "Chrome",
      "ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/46.0.2490.86 Safari/537.36"
    },
    "ip": "108.0.78.21",
    "utm": {
      "campaign": "TPS Innovation Newsletter",
      "source": "Newsletter",
      "medium": "email",
      "term": "tps reports",
      "content": "image link"
    }
  },
  "event": "productViewed",
  "messageId": "ajs-f8ca1e4de5024d9430b3928bd8ac6b96",
  "properties": {
    "currency": "INR",
    "filters": "Price < 5000",
    "sort": "Price (Low to High)",
    "product": {
      "name": "Earbuds",
      "category": "Mobile Phone & Accessories",
      "position": 1
    }
  },
  "receivedAt": "2015-12-12T19:11:01.266Z",
  "sentAt": "2015-12-12T19:11:01.169Z",
  "timestamp": "2015-12-12T19:11:01.249Z",
  "type": "track",
  "originalTimestamp": "2015-12-12T19:11:01.152Z",
  "writeKey": "aUL2rZghe5jHvjWh"
}

Propagating events to destinations

Events collected via the Track API are forwarded to configured destinations unless explicitly excluded.

  • Default Behavior: Events and properties are passed to all mapped destinations.
  • Compatibility:
    • If a destination does not support properties, only the event name is sent.
    • If a property type is unsupported, it will be converted or excluded, based on feasibility.

This ensures seamless integration across all destinations while maintaining data fidelity where possible.