Tracking Events

Any action of interest done by a user is an event. For example, in case of an e-commerce app when a user adds an item to the shopping cart, the app 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.

Each event has a name and an optional set of attributes describing the event in detail as necessary. An event attribute is a piece of data associated with an event. In the above example, product details and price are the “Added to Cart” event attributes. We recommend you make your events human readable - as an example, you can use a verb in the past tense like “Product Searched” and “Added to Cart”.

Event tracking lets you track user actions in your app, 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.

Events accumulate over time, and WebEngage sends events in batches periodically to minimize network usage and maximize battery life.

System events

WebEngage starts tracking some events automatically as soon as you integrate the SDK. These are called System Events and they track your users’ interactions with your app and campaigns. Note that 2 system events are not tracked automatically - User Login and User Logout.

System events make it easier to analyze user behavior 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 can find the list of system events tracked by WebEngage here.

Please note that sdk_id attribute ('Platform' on WebEngage dashboard) of these events signifies the SDK. sdk_id is 1 for Web, 2 for Android and 3 for iOS.

Custom events

Custom events enable you to track user actions in your app. All Events related APIs are part of WebEngage Android SDK's Analytics object. You get an instance of WebEngage Analytics object as follows.

// import WebEngage ‘Analytics’

// Get an instance of ‘Analytics’ object
Analytics weAnalytics = WebEngage.get().analytics();


  • Event names must be less than 50 characters long.
  • Event attributes can be of these data types: String, all subclasses of Number, Boolean, Date, List, Map.
  • Event attribute names must be less than 50 characters long. String type attribute values must be less than 1000 characters long.
  • You cannot start your event or event attribute names with we_.
  • You can create at most 25 event attributes of each data type across all instances of an event.
  • If event attribute value is List or Map, it cannot be used to create user segments. It can only be used to personalize campaigns.

After WebEngage has been successfully initialized, you can track an event as follows.

weAnalytics.track("Product - Page Viewed");

If you want to add attributes to the event you are tracking, you can use a Map to specify them and then attach to the event as follows.

Map<String, Object> addedToCartAttributes = new HashMap<>();
addedToCartAttributes.put("Product ID", 1337);
addedToCartAttributes.put("Price", 39.80);
addedToCartAttributes.put("Quantity", 1);
addedToCartAttributes.put("Product", "Givenchy Pour Homme Cologne");
addedToCartAttributes.put("Category", "Fragrance");
addedToCartAttributes.put("Currency", "USD");
addedToCartAttributes.put("Discounted", true);

weAnalytics.track("Added to Cart", addedToCartAttributes);

Map<String, Object> orderPlacedAttributes = new HashMap<>();
orderPlacedAttributes.put("Amount", 808.48);
orderPlacedAttributes.put("Product 1 SKU Code", "UHUH799");
orderPlacedAttributes.put("Product 1 Name", "Armani Jeans");
orderPlacedAttributes.put("Product 1 Price", 300.49);
orderPlacedAttributes.put("Product 1 Size", "L");
orderPlacedAttributes.put("Product 2 SKU Code", "FBHG746");
orderPlacedAttributes.put("Product 2 Name", "Hugo Boss Jacket");
orderPlacedAttributes.put("Product 2 Price", 507.99);
orderPlacedAttributes.put("Product 2 Size", "L");
String dateStr = "2017-10-06T09:27:37Z";
SimpleDateFormat format = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss'Z'");
try {
    Date date = format.parse(dateStr);
    orderPlacedAttributes.put("Delivery Date", date);
} catch (ParseException e) {
orderPlacedAttributes.put("Delivery City", "San Francisco");
orderPlacedAttributes.put("Delivery ZIP", "94121");
orderPlacedAttributes.put("Coupon Applied", "BOGO17");

weAnalytics.track("Order Placed", orderPlacedAttributes);

1. Event names are case sensitive.
2. eventName must not start with we_. Event names starting with we_ are reserved for WebEngage's internal use, and will be ignored if used for custom events.
3. For custom events, the first datapoint synced to WebEngage defines the data type for that event attribute in WebEngage. Therefore, data types must be consistent with the data that you want to store for the attribute. If you change the data type later, attribute data will stop flowing to WebEngage.

Event priority

Events accumulate over time, and WebEngage sends events in batches periodically to minimize network usage and maximize battery life of the device. Event priority allows you to override this behaviour of the SDK.

You can set any particular event's priority to be high as shown below. WebEngage SDK reports all such events immediately (provided network connectivity is available), and does not batch them with events whose priority is not set to high.

weAnalytics.track("Checkout Started", new Analytics.Options().setHighReportingPriority(true));

You can also set high priority to events with attributes as shown below.

Map<String, Object> checkoutStartedAttributes = new HashMap<>();
checkoutStartedAttributes.put("Cart ID", 35651);
checkoutStartedAttributes.put("Cart Size", 3);
checkoutStartedAttributes.put("Cart Value", 445.59);
checkoutStartedAttributes.put("Cart Category", "Women Dresses");

weAnalytics.track("Added to Cart", checkoutStartedAttributes, new Analytics.Options().setHighReportingPriority(true));

Note that high priority events are reported more frequently since they are not batched. This behaviour will make your app drain the device battery faster. You must use this feature sparingly, only when it is necessary.

setHighReportingPriority works only when reporting strategy is set to BUFFER. In case reporting strategy is set to FORCE_SYNC, all of your events are being reported with high priority already.

Complex event attributes

WebEngage allows you to pass complex event attributes as List and Map data types. You will be able to use these complex attributes to personalize campaigns as shown below.

Note that you will not be able to use complex attributes as segment filters, as you can see in the segment creation screen below.

You can pass complex event attributes as illustrated below.

Map<String, Object> product1 = new HashMap<>();
product1.put("SKU Code", "UHUH799");
product1.put("Product Name", "Armani Jeans");
product1.put("Price", 300.49);

Map<String, Object> detailsProduct1 = new HashMap<>();
detailsProduct1.put("Size", "L");
product1.put("Details", detailsProduct1);

Map<String, Object> product2 = new HashMap<>();
product2.put("SKU Code", "FBHG746");
product2.put("Product Name", "Hugo Boss Jacket");
product2.put("Price", 507.99);

Map<String, Object> detailsProduct2 = new HashMap<>();
detailsProduct2.put("Size", "L");
product2.put("Details", detailsProduct2);

Map<String, Object> deliveryAddress = new HashMap<>();
deliveryAddress.put("City", "San Francisco");

Map<String, Object> orderPlacedAttributes = new HashMap<>();
orderPlacedAttributes.put("Products", Arrays.asList(product1, product2));
orderPlacedAttributes.put("Delivery Address", deliveryAddress);
orderPlacedAttributes.put("Coupons Applied", Arrays.asList("BOGO17"));

weAnalytics.track("Order Placed", orderPlacedAttributes);

Updated 6 months ago

So, what's next?

Push messaging

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.