Document Categories

Tracking Events

Usermost offers API for tracking events. This can be done using the /eventsendpoint as described below.

Any action of interest done by a user is an event. For example, in case of an e-commerce website when a user adds an item to the shopping cart, the website would want to record the “Added to Cart” event along with the product details and price. Events may also be actions carried out by your system in the context of a user, say to track the user’s inactivity or to notify departure of a shipment.

Event tracking lets you track user actions on your website, which enables you to create user segments and engagement campaigns based on this activity. We have put together a list of event templates for you to refer to.

System events

Usermost starts tracking some events automatically as soon as you integrate any of the SDKs. These are called System Events and they track your users’ interactions with your apps, website and campaigns. System events make it easier to analyze user behaviour and optimize your marketing around common business goals such as driving user registrations or purchases. You can use custom events for any other user actions you want to track.

You cannot create system events using Usermost API.

Using Usermost API, you should avoid creating events with the same event name as that of system events to avoid confusion.

Custom events

Custom events enable you to track user actions in your app. /eventsAPI only creates custom events.

There are two types of passing events to Usermost:

  1. Sending each event in separate request (/events)
  2. Sending a list of events in batch request (/eventsBatch)

METHOD:
POST

DESCRIPTION:
Track custom events.

URL STRUCTURE:

<HOST>/v1/accounts/<YOUR_USERMOST_LICENSE_CODE>/events

<HOST>/v1/accounts/<YOUR_USERMOST_LICENSE_CODE>/eventsBatch

HEADERS

NameDescription
x-request-id:{HEX_STRING}Replace {HEX\_STRING}with a unique random hex string.If API re-attempts are being made, this tag stops propagation of duplicate events within a 4 hour window. Events with same ID re-attempted within 4 hours won’t get duplicated if the previous HTTPrequest was able to ingest the event.

EXAMPLE

Sending an event in a request:

curl -X POST <HOST>/v1/accounts/<YOUR_USERMOST_LICENSE_CODE>/events \
    –header 'Authorization: Bearer <YOUR_API_KEY>' \
    –header 'Content-Type: application/json' \
    –data '{
		"userId": "16135550138",
		"eventName": "Added to Cart",
		"eventTime": "2018-09-15T18:29:00-0800",
		"targetId": "23980998748",
		"points": "10",
                "eventData": {
                    "field1":"test",
                    "field2":122,
                    "field3":true,
                    "field4":"2020-07-27T18:54:30+0430"
                }
	}'

Sending a batch of events in a request:

curl -X POST <HOST>/v1/accounts/<YOUR_USERMOST_LICENSE_CODE>/eventsBatch \
    –header 'Authorization: Bearer <YOUR_API_KEY>' \
    –header 'Content-Type: application/json' \
    –data '{
	"list": [
			{
				"userId": "16135550138",
				"eventName": "Added to Cart",
				"eventTime": "2018-09-15T18:29:00-0800",
				"targetId": "23980998748",
				"points": "10",
 				"eventData": {
  				  "field1":"test",
 				   "field2":122,
  				  "field3":true,
  				  "field4":"2020-07-27T18:54:30+0430"
  				}
			},
			{
				"userId": "16135550138",
				"eventName": "Added to Cart",
				"eventTime": "2018-09-15T18:29:00-0800",
				"targetId": "23980998749",
				"points": "11",
				"eventData": {
 				   "field1":"test",
  				   "field2":122,
  				   "field3":true,
 				   "field4":"2020-07-27T18:54:30+0430"
 				 }
			}
	]
	}'

PARAMETERS

Sending an event in a request:

{	
	"userId": "16135550138",
	"eventName": "Added to Cart",
	"eventTime": "2018-09-15T18:29:00-0800",
	"targetId": "23980998748",
	"points": "10",
	"eventData": {
  	  "field1":"test",
  	  "field2":122,
	  "field3":true,
  	  "field4":"2020-07-27T18:54:30+0430"
 	}
}

Sending a batch of events in a request:

{
	"list": [
			{
				"userId": "16135550138",
				"eventName": "Added to Cart",
				"eventTime": "2018-09-15T18:29:00-0800",
				"targetId": "23980998748",
				"points": "10",
				"eventData": {
				    "field1":"test",
				    "field2":122,
				    "field3":true,
 				   "field4":"2020-07-27T18:54:30+0430"
 				}
			},
			{
				"userId": "16135550138",
				"eventName": "Added to Cart",
				"eventTime": "2018-09-15T18:29:00-0800",
				"targetId": "23980998749",
				"points": "11",
				"eventData": {
				    "field1":"test",
				    "field2":122,
				    "field3":true,
 				   "field4":"2020-07-27T18:54:30+0430"
 				}
			}
	]
}

Constraints:

  • Event names must be less than 50 characters long.
  • You cannot start your event names with um_.
  • Maximum size of event list in batch request can be 100.
ParameterTypeDescriptionIs mandatory
userIdStringIdentifier for known user.
Either one of userId or deviceId mandatory. User ID or device ID can be found on the respective user’s profile screen on Usermost dashboard.
Constraint:
● userId can be of maximum 100 characters.
 
Yes
deviceIdStringIdentifier for anonymous user. Either one of userId or deviceId is mandatory. In case both IDs are sent, deviceId will be ignored. User ID or device ID can be found on the respective user’s profile screen on Usermost dashboard.
Constraint:
● deviceId can be of maximum 100 characters.
 
No
eventNameStringName of the event.Yes
eventTimeStringDate and time when the event occurred in ISO format: yyyy-MM-ddTHH:mm:ss±hhmm.No
targetIdStringRefers to an object that the event happens on. For example viewing a specific product.No
pointsIntegerPoint of the event. If not provided, the default value is automatically set.No
eventDataJSONA JSON object to send custom attributesNo

RETURNS:

{
	"response": {
		"status": "queued"
	}
}

ERRORS:


Example: userId missing

{
	"response": {
		"message": "Error: userId and deviceId cannot be empty.",
		"status": "error"
	}
}

Custom Attributes

Custom Attributes are details that can be attached to each Custom Event defined by you. You can choose to attach a maximum if 25 custom attributes of a single data type to each Custom Event to better understand each user’s platform interactions and contextually engage them.

For example, if an ed-tech platform tracks course purchases as the Custom Event, Course-Enrolled then it’s Custom Event Attributes would be:

  • Course Name
  • Course ID
  • Course Value
  • Course Duration
  • Number of Chapters
  • Course Category and so on.

Tracking Custom Events & Custom Event Attributes

System Events and System Event Attributes are automatically tracked by Usermost once you send the first Event through our API. However, you will need to specifically define and pass each Custom Event and their Custom Attributes from your various platforms to your Usermost account.

Here are a few guidelines to help you get started:

  • Please ensure consistent usage of the names of Custom Events and their Custom Attributes. Doing so will make it easier for you to segment users, personalize campaigns and configure campaign targeting in your dashboard.
  • We highly recommend that you create an excel sheet to list down:
    • The Custom Events you want to track.
    • The corresponding Custom Attributes of each Event.
    • The data type of the values you will be tracking against each Custom Attribute.
  • Data types must be consistent with the value that you want to store against the attribute. If the data type is changed at a later date, then Custom Event Attribute data will stop flowing to your Usermost dashboard.
    • You can create a maximum of 25 Event Attributes of each data type for a Custom Event. (ie. 25 attributes of Number data type, 25 attributes of String, Date and Boolean data type).
  • Custom Event and Custom Event Attribute names are case sensitive must be less than 50 characters long. String attribute values must be less than 1000 characters long.
    • Names must not start with um_ as the term is reserved exclusively for internal use at Usermost. Thus, to avoid data contamination for your account, such data will be ignored if used for your Custom Events.

508 reads

Table of Contents

Let’s schedule your personalized demo