Skip to content

Tracardi integration

Integrating Tracardi with a web page or other systems is easy by calling the Tracardi endpoint.

Events can be sent via the /track endpoint using the POST method in the following JSON format:

{
  "source": {
    "id": "Source ID"
  },
  "session": {
    "id": "Session ID"
  },
  "profile": {
    "id": "Profile ID"
  },
  "context": {
    // Context data
  },
  "properties": {},
  "events": [
    {
      "type": "event-type",
      "properties": {
        // Event properties
      },
      "options": {
        // Event options
      },
      "context": {
        // Additional context data
      }
    },
    ...
  ],
  "options": {}
}

The above data is referred to as the "tracker payload" in Tracardi documentation and consists of the following data:

  • source.id - this is the UUID that identifies the source. It must match the source ID that is defined in Tracardi. Otherwise, the system will return an "Unauthorized Access" response.
  • session.id - it is a UUID generated and saved on the client's side. Whenever the session changes or a new customer visit starts, a new session ID is generated.
  • profile.id - this is the UUID of the profile ID. The profile ID must remain unchanged during the entire customer journey. The profile ID is generated on the server side. When the first event is sent to Tracardi, the system will return a generated profile ID that needs to be saved by the client (browser or mobile device) and resent with each subsequent event. Tracardi has several algorithms that try to keep the profile ID unchanged during the entire customer journey. Some of those algorithms will be described below.
  • context - this is a JSON data that describes the context of the event. It can be an agent type, e.g. mobile app name, service name. This part is defined by the user.
  • events - this is a collection of event objects called Event Payload, that consist of: type, properties, context, time, tags, and options. See here for more details.
  • options - this is a key-value store for additional options.

Tracardi can collect several events in one request. That's why we define a list of objects in the events key. Each event may have different context and can also inherit values from the tracker payload. Here's an example of the tracker payload that could be sent to Tracardi.

{
  "source": {
    "id": "3ee63fc6-490a-4fd8-bfb3-bf0c8c8d3387"
  },
  "session": {
    "id": "bfb3-bf0c8c8d3387-3ee63fc6-490a-4fd8"
  },
  "profile": {
    "id": "bf0c8c8d3387-3ee63fc6-490a-4fd8bfb3"
  },
  "context": {
    "system": "webstore-backend",
    "webstore": {
      "url": "http://magento-store.com",
      "name": "Shoe store"
    },
    "client": {
      "browser": "Mozilla Firefox"
    }
  },
  "properties": {},
  "events": [
    {
      "type": "page-view",
      "properties": {
        "pageTitle": "My Page"
      },
      "options": {
        "saveEvent": false,
        "saveSession": false,
        "debugger": false
      },
      "context": {
        "tag": "product-details-page"
      }
    },
    {
      "type": "consent-granted",
      "properties": {
        "marketing": false,
        "general": true
      },
      "options": {
        "profile": true,
        "saveSession": false
      }
    },
    {
      "type": "product-in-basket",
      "properties": {
        "product": "Adidas sneakers",
        "price": 34.43
      },
      "options": {
        "profile": false,
        "logs": false
      }
    }
  ],
  "options": {}
}

This is a full-fledged tracker payload with a lot of data. But not all the fields are required.

The required fields are:

  • source.id, session.id, profile.id - if exists, and collection of events

Minimalistic tracker payload could look like this:

{
  "source": {
    "id": "f14dc4b1-8dd8-4fc1-bd14-d6823ba7013e"
  },
  "session": {
    "id": "d6823ba7013e-8dd8-4fc1-bd14-f14dc4b1"
  },
  "events": [
    {
      "type": "page-view",
      "properties": {
        "pageTitle": "My Page"
      }
    },
    {
      "type": "consent-granted",
      "properties": {
        "marketing": false,
        "general": true
      }
    },
    {
      "type": "product-in-basket",
      "properties": {
        "product": "Adidas sneakers",
        "price": 34.43
      }
    }
  ]
}

Understanding Customer Identification in Tracardi

Tracardi uses two IDs to identify customers: the profile ID and the session ID. Both of these IDs need to be included in every tracker payload when sending data to Tracardi. The session ID can be generated on the client side using a UUID4 ID, which is a unique identifier, to handle cases where the session is missing. On the other hand, the profile ID is generated by Tracardi's backend and is not available when a customer visits the page for the first time.

Obtaining the Profile ID

To obtain the profile ID, the recommended approach is to send the tracker payload without setting the profile ID, and only generate the session ID. Tracardi will then return the generated profile ID, which needs to be saved on the client side. This is how the Tracardi JavaScript snippet works, by saving the profile ID in the browser's localStorage and the session ID in cookies.

Understanding the Profile

The profile is a critical part of the payload, and Tracardi aims to keep the profile unchanged at all times to ensure accurate tracking and profiling of customer behavior. Therefore, it is important for the client to save the profile ID and include it in every call to the /track endpoint.

However, there may be cases where the profile is missing and needs to be created. This can happen in the following scenarios:

  • If the payload does not provide a profile ID, such as the first call to Tracardi when the customer's profile ID is unknown and needs to be created
  • The profile ID is provided, but it does not exist in Tracardi's database.
  • If a profile ID is not provided in the tracker payload, but a valid previous session is provided, the system will search for the lost profile by matching the last valid session and return the correct profile ID.

It is crucial to synchronize the profile ID returned in the response with the profile ID saved on the client side. If the profile ID in the response is different from the one sent, it means that the client should update its profile ID and include the new one in the next call to avoid potential synchronization issues. Failing to do so may result in the profile ID being recreated with each call to the /track API, which can lead to inaccurate tracking and profiling of customer behavior.

Understanding Sessions in Tracardi

A session in Tracardi is equivalent to a visit, representing the duration of a user's interaction with a website or application. Ideally, a session should remain the same during one visit, but should change when the user closes their browser or logs out.

Changing Session ID while Keeping Profile

In some cases, the client may want to keep the profile unchanged but change the session ID. To achieve this, the client can provide the profile ID while generating a new session ID. This will result in a new session being created, while the profile remains unchanged, and the system generates a new visit for the user.

Sending Same Session ID with Tracking Payloads

While it is possible to send the same session ID with all the tracking payloads, allowing the system to keep the session and profile unchanged, this practice is not suggested. This is because if a profile is saved with only one visit, it will not be possible to change the visits associated with the profile. It is recommended to generate a new session ID for each visit to ensure accurate tracking and profiling of user behavior.

It is important to note that the session and profile management in Tracardi is crucial for accurate tracking and profiling of user interactions. By understanding how sessions work and following recommended practices, clients can effectively utilize Tracardi's capabilities to analyze and understand user behavior on their website or application.