Tracking Events

WebEngage offers API for tracking Custom Events through the /events endpoint described below.

Must Read

We recommend that you get yourself acquainted with the concept of System Events, Custom Events and their attributes before proceeding. Doing so will help you better understand the type of Events that can be created through our APIs.

Here are a few Custom Event Templates to help you get started.

WebEngage starts tracking some events as soon as you integrate your platforms through our SDK. These are called System Events and track some generic user interactions with your app and campaigns.

You can create Custom Events to track any other user interactions that are crucial for your business. Each Custom Event can further be defined by Event Attributes like price, quantity, category and so on. Such granular data enables you to engage users through highly contextual and personalized campaigns through all the channels of engagement.

Guidelines for Tracking Custom Events

Here are a few things to keep in mind:

  • Custom Event names must be less than 50 characters long.

  • Custom Event Attribute names are case sensitive and must be less than 50 characters long. String attribute values must be less than 1000 characters long.

  • These data types are allowed for event attributes: String, Number, Boolean, Date, JSON Array, JSON Object. JSON Object can contain only one of these data types.

  • eventName or eventAttributeName must not start with we_. Names starting with we_ are reserved exclusively for internal use at WebEngage. Thus, to avoid data contamination for your account, such data will be ignored if used for your Custom Events.

  • You can create a maximum of 25 Event Attributes of each data type for a Custom Event.

  • If event attribute value is JSON Object, it cannot be used to create user segments. It can only be used to personalize campaigns.

  • The first datapoint synced to WebEngage defines the data type for that event attribute. Thus, 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 WebEngage dashboard.

/events

  1. You cannot create System Events using the WebEngage API. Here's a list of the System Events that are automatically tracked by WebEngage.

  2. Please avoid creating Custom Events of the same name as that of System Events through the API to avoid confusion.

METHOD: POST

DESCRIPTION: Tracks custom events.

URL STRUCTURE: <HOST>/v1/accounts/<YOUR_WEBENGAGE_LICENSE_CODE>/events

Headers

Name
Description

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 HTTP request was able to ingest the event.

AUTHENTICATION: User Authentication

EXAMPLE

curl -X POST <HOST>/v1/accounts/<YOUR_WEBENGAGE_LICENSE_CODE>/events \
    --header 'Authorization: Bearer <YOUR_API_KEY>' \
    --header 'Content-Type: application/json' \
    --data '{
		"userId": "johndoe",
		"eventName": "Added to Cart",
		"eventTime": "2018-09-15T18:29:00-0800",
		"eventData": {
				"Product ID": 1337,
				"Price": 39.80,
				"Quantity": 1,
				"Product": "Givenchy Pour Homme Cologne",
				"Category": "Fragrance",
				"Currency": "USD"
    }
}'

Run in Postman

Please ensure that you:

Parameters

{
		"userId": "johndoe",
		"eventName": "Added to Cart",
		"eventTime": "2018-09-15T18:29:00-0800",
		"eventData": {
				"Product ID": 1337,
				"Price": 39.80,
				"Quantity": 1,
				"Product": "Givenchy Pour Homme Cologne",
				"Category": "Fragrance",
				"Currency": "USD"
    }
}
Parameter
Type
Description
Is mandatory

userId

String

Identifier for known user.
Either one of userId or anonymousId is mandatory.

User ID or Anonymous ID can be found on the respective user's profile screen on WebEngage dashboard.

Constraint:

  • userId can be of maximum 100 characters.

No

anonymousId

String

Identifier for anonymous user. Either one of userId or anonymousId is mandatory. In case both IDs are sent, anonymousId will be ignored.

User ID or Anonymous ID can be found on the respective user's profile screen on WebEngage dashboard.

Constraint:

  • anonymousId can be of maximum 100 characters.

No

eventName

String

Name of the event.

Yes

eventTime

String

Date and time when the event occurred in ISO format: yyyy-MM-ddTHH:mm:ss±hhmm.

No

eventData

String

Event attributes as key-value pairs. For example:
{ "Product ID": 1337, "Category": "Fragrance" }
These data types are allowed for custom attributes: String, Number, Boolean, Date, JSON Array, JSON Object. JSON Object can contain one of these data types.

No

Returns

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

Errors

Example: Both userId and anonymousID are missing.

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

Please feel free to drop in a few lines at [email protected] or get in touch with your Onboarding Manager in case you have any further queries. We're always just an email away!

Updated 5 days ago

Tracking Events


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.