Skip to content

API integration

Event can be sent via Tracardi API. The APi is located at /track endpoint and takes data with POST method in the following format.

{
  "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": {}
}

The above data is called tracker payload and consists of the following data:

  • source.id - this is the UUID that identifies source. It must much the source id that is defined in Tracardi. Otherwise, the system will return UnAuthorized Access response.
  • session.id - it is a UUID generated and saved on the clients side. Whenever the session changes the new profile id is generated by tracardi. Unless the tracker payload profile filed is defined. Then the old profile id is returned.
  • metadata.time - this is time of event. If not set it will be generated on server side.
  • profile.id - this is UUID of profile id. If the session sent with this tracker payload does not match any session in tracardi the profile.id is used to restore user profile. user profile should be saved on client side and send with all payload. If the user profile.id does not exist in Tracardi new user profile will be generated and send back in response.
  • context - this 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 user
  • events - its a collection of event objects that consist of: type, properties, context, and options. See below for more details
  • options - this is a key value store for additional 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"
      },
      "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
      }
    }
    ]
}

Profile

Profile is the most important part in the payload. And Tracardi strives to keep the profile all the time the same, and do not change it. Therefore, client should save the profile id and pass it with every call to /track endpoint.

But there are use cases when the profile is lost and will be recreated.

  • If a payload does not provide profile id or the profile id does not exist in Tracardi database
  • If the session does not exist and profile is not provided. If profile id is provided but session id does not exist new session will be created but the profile will stay the same.

It is very important to synchronize profile.id returned in response with the profile id saved on a client side. When the profile in response is different from the one we have sent that it means that the client should update its profile.id and send new one with the next call. If you miss this part then the profile.id will be recreated with each call to /track API. That may ruin the whole profile.

Session

Session is equivalent to visit so session should stay the same during one visit but should change when user closes the browser or logs out.

Tracker response

{
  "debugging": {
    "session": {
      "saved": 1,
      "errors": [],
      "ids": [
        "string"
      ],
      "types": []
    },
    "events": {
      "saved": 0,
      "errors": [],
      "ids": [],
      "types": []
    },
    "profile": {
      "saved": 1,
      "errors": [],
      "ids": [
        "0d2d9dc5-0d60-471e-956f-8766dcb8aba2"
      ],
      "types": []
    },
    "execution": {},
    "segmentation": {
      "errors": [],
      "ids": []
    },
    "logs": []
  },
  "profile": {
    "id": "0d2d9dc5-0d60-471e-956f-8766dcb8aba2"
  },
  "source": {
    "consent": false
  }
}

Response - 422 Unprocessed entity

This error occurs when the tracker payload is missing some data. Usually it will happen when you miss required field.

Response - Unauthorized

This error occurs when the source.id that is sent with payload does not exist in Tracardi.

Response - Headers

With response there is a x-process-time header thar returns how much time it took to process the request.