Documentation > Docs

Working with Events

What are Events or User Actions?

Events are people-centric. Unlike page-views, which simply track pages clicked on, events track what individual actions users perform in your app or website – like a user Viewing a Product, Listening to a Song, Sharing a Photo, Making a Purchase or Favoriting an Item. Events help you understand what users are doing in your app or website.

While you should record any event that’s important to your business, we recommend that you start off with a few during your initial integration.

What are Event Properties?

Events have details that describe the action taking place, called properties. Properties are essentially more details about your events. For example, while recording the “Product viewed” event, you could also store Event Properties like product name, category, and price.

In the above example, recording Event Properties will help you answer questions like which category of products are more popular, and help you segment users based on which categories or price points they’ve viewed.

Events recorded automatically

While you can record any custom event along with properties, CleverTap records the below listed User Events automatically to simplify your life.

App Launched

This event is recorded every time a user launches your app. The App Launched event is recorded when either of the following conditions are met:

  1. Fresh app launch or via a push notification link
  2. When the app is brought to the foreground after 20 minutes of inactivity

UTM Visited

This event is used to track campaign visits. It is recorded for users who visit your website, or launch your app with source, medium and/or campaign parameters in the URL.

Clicks on all campaigns sent via CleverTap are also tracked using the UTM Visited event. UTM Visited event is also recorded for your marketing campaigns from external sources such as Google Adwords, Adroll, etc.

Android Push notifications containing deep links to third-party apps are not tracked

Notification Viewed

This event is recorded when a user views an email, in-app, or a web notification sent out using CleverTap.

Notification Sent

This event is used to track whenever a message from a campaign is sent to a user. This event is recorded regardless of whether the user opens or clicks on the message and is applicable to Email, Push SMS, Web Push or Facebook Audience campaigns.

App Uninstalled

This is an App only event, and is recorded for users who uninstall your app. Learn more about App Uninstalled Event

Metadata recorded automatically

For every event that’s recorded, CleverTap records the following standard metadata –

  • Information about the user who performed the event
  • Date and time when the event was recorded
  • The number of screens viewed by the user before performing the action
  • The time spent in the app or on the website before performing the action
  • The referring site and the source of the user visit if it was from an external source.

Additionally, CleverTap keeps the user profiles updated with the latest –

  • Geographic information like their city, region, country, and latitude/longitude (if available).
  • Browser or device make, model, etc. used to access the website or app

Recording User Events

Recording a User Events is very simple. To record an Event called Product viewed when a user views a product, you can use the following code snippet –

Select Platform
// event without properties
cleverTap.event.push("Product viewed");
copy Copied
// event without properties
[[CleverTap sharedInstance] recordEvent:@"Product viewed"];
copy Copied
// event without properties
CleverTap.sharedInstance()?.recordEvent("Product viewed")
copy Copied
// event without properties
clevertap.event.push("Product viewed");
copy Copied
// event without properties
CleverTapInstance.Event.Push("Product viewed");
copy Copied
// event without properties
CleverTapInstance.Event.Push("Product viewed");
copy Copied

Adding properties to an Event

Use the following code snippet to record properties along with the Event

Select Platform
// event with properties
HashMap<String, Object> prodViewedAction = new HashMap<String, Object>();
prodViewedAction.put("Product Name", "Casio Chronograph Watch");
prodViewedAction.put("Category", "Mens Accessories");
prodViewedAction.put("Price", 59.99);
prodViewedAction.put("Date", new java.util.Date());

cleverTap.event.push("Product viewed", prodViewedAction);

/**
 * Data types
 * The value of a property can be of type Date (java.util.Date), an Integer, a Long, a Double,
 * a Float, a Character, a String, or a Boolean.
 *
 * Date object
 * When a property value is of type Date, the date and time are both recorded to the second.
 * This can be later used for targeting scenarios.
 * For e.g. if you are recording the time of the flight as an event property,
 * you can send a message to the user just before their flight takes off.
 */
copy Copied
// event with properties
NSDictionary *props = @{
    @"Product name": @"Casio Chronograph Watch",
    @"Category": @"Mens Accessories",
    @"Price": @59.99,
    @"Date": [NSDate date]
};

[[CleverTap sharedInstance] recordEvent:@"Product viewed" withProps:props];

/**
 * Data types:
 * The value of a property can be of type NSDate, a NSNumber, a NSString, or a BOOL.
 *
 * NSDate object:
 * When a property value is of type NSDate, the date and time are both recorded to the second.
 * This can be later used for targeting scenarios.
 * For e.g. if you are recording the time of the flight as an event property,
 * you can send a message to the user just before their flight takes off.
 */
copy Copied
// event with properties
let props = [
    "Product name": "Casio Chronograph Watch",
    "Category": "Mens Accessories",
    "Price": 59.99,
    "Date": NSDate()
]

CleverTap.sharedInstance()?.recordEvent("Product viewed", withProps: props)

/**
 * Data types:
 * The value of a property can be of type NSDate, a Number, a String, or a Bool.
 *
 * NSDate object:
 * When a property value is of type NSDate, the date and time are both recorded to the second.
 * This can be later used for targeting scenarios.
 * For e.g. if you are recording the time of the flight as an event property,
 * you can send a message to the user just before their flight takes off.
 */
copy Copied
// event with properties
clevertap.event.push("Product viewed", {
    "Product name": "Casio Chronograph Watch",
    "Category": "Mens Accessories",
    "Price": 59.99,
    "Date": new Date()
});

/**
 * Data types
 * Event property keys must be Strings and property values must, with certain specific exceptions,
 * be scalar values, i.e. String, Boolean, Integer, or Float, or a Date object.
 *
 * Date object
 * When a property value is of type Date, the date and time are both recorded to the second.
 * This can be later used for targeting scenarios.
 * For e.g. if you are recording the time of the flight as an event property,
 * you can send a message to the user just before their flight takes off.
 */
copy Copied
// event with properties
Dictionary<string, object> evtProps = new Dictionary<string, object>();
evtProps.Add("Product name", "Casio Chronograph Watch");
evtProps.Add("Category", "Mens Accessories");
evtProps.Add("Price", 59.99);

CleverTapInstance.Event.Push("Product viewed", evtProps);

/**
 * Data types
 * The value of a property can be either a DateTime, an Integer, a Long, a Double,
 * a Float, a Character, a String, or a Boolean.
 *
 * Date object
 * When you pass the value of the property as DateTime, the date and time are both recorded to the second.
 * This can be later used for targeting scenarios.
 * For e.g. if you are recording the time of the flight as an event property,
 * you can send a message to the user just before their flight takes off.
 */
copy Copied
// event with properties
Dictionary<string, object> evtProps = new Dictionary<string, object>();
evtProps.Add("Product name", "Casio Chronograph Watch");
evtProps.Add("Category", "Mens Accessories");
evtProps.Add("Price", 59.99);

CleverTapInstance.Event.Push("Product viewed", evtProps);

/**
 * Data types
 * The value of a property can be either a DateTime, an Integer, a Long, a Double,
 * a Float, a Character, a String, or a Boolean.
 *
 * Date object
 * When you pass the value of the property as DateTime, the date and time are both recorded to the second.
 * This can be later used for targeting scenarios.
 * For e.g. if you are recording the time of the flight as an event property,
 * you can send a message to the user just before their flight takes off.
 */
copy Copied

Recording Customer Purchases

You should record transactions or purchases in CleverTap using a special event called Charged.

What makes Charged a special event?

Charged is a special event because it provides a way for you to specify the items sold, their categories, transaction amount, the transaction id, and the information about your users.

Recording a purchase against a user marks them as a customer in CleverTap. This enables you to compare your funnel reports between customers and non-customers.

Recording items sold

To record a list of items sold, you should use the Items collection. See the code sample below. Along with the product name, you can also add properties like size, color, category etc.

Recording the transaction amount

The transaction total or subscription charge should be recorded in an event property called Amount.

Avoiding duplicate transactions

Along with other properties of the transaction, you can also send the transaction identifier in the Charged ID property. CleverTap uses the Charged ID property to ensure that duplicate Charged events don’t get recorded in case of network failure or retries. Ideally, you should set transaction ID or the receipt ID generated at your end as a value of the Charged ID property.

Select Platform
HashMap<String, Object> chargeDetails = new HashMap<String, Object>();
chargeDetails.put("Amount", 300);
chargeDetails.put("Payment Mode", "Credit card");
chargeDetails.put("Charged ID", 24052013); // important to avoid duplicate transactions due to network failure

HashMap<String, Object> item1 = new HashMap<String, Object>();
item1.put("Product category", "books");
item1.put("Book name", "The Millionaire next door");
item1.put("Quantity", 1);

HashMap<String, Object> item2 = new HashMap<String, Object>();
item2.put("Product category", "books");
item2.put("Book name", "Achieving inner zen");
item2.put("Quantity", 1);

HashMap<String, Object> book3 = new HashMap<String, Object>();
item3.put("Product category", "books");
item3.put("Book name", "Chuck it, let's do it");
item3.put("Quantity", 5);

ArrayList<HashMap<String, Object>> items = new ArrayList<HashMap<String, Object>>();
items.add(item1);
items.add(item2);
items.add(item3);

try {
    cleverTap.event.push(CleverTapAPI.CHARGED_EVENT, chargeDetails, items);
} catch (InvalidEventNameException e) {
    // You have to specify the first parameter to push()
    // as CleverTapAPI.CHARGED_EVENT
}
copy Copied
NSDictionary *chargeDetails = @{
   @"Amount" : @300,
   @"Payment mode": @"Credit Card",
   @"Charged ID": @24052013 // important to avoid duplicate transactions due to network failure
};

NSDictionary *item1 = @{
   @"Category": @"books",
   @"Book name": @"The Millionaire next door",
   @"Quantity": @1
};

NSDictionary *item2 = @{
   @"Category": @"books",
   @"Book name": @"Achieving inner zen",
   @"Quantity": @1
};

NSDictionary *item3 = @{
   @"Category": @"books",
   @"Book name": @"Chuck it, let's do it",
   @"Quantity": @5
};

NSArray *items = @[item1, item2, item3];
[[CleverTap sharedInstance] recordChargedEventWithDetails:chargeDetails
                                                 andItems:items];
copy Copied
let chargeDetails = [
    "Amount": 300,
    "Payment mode": "Credit Card",
    "Charged ID": 24052013
]

let item1 = [
    "Category": "books",
    "Book name": "The Millionaire next door",
    "Quantity": 1
]

let item2 = [
    "Category": "books",
    "Book name": "Achieving inner zen",
    "Quantity": 1
]

let item3 = [
    "Category": "books",
    "Book name": "Chuck it, let's do it",
    "Quantity": 5
]

CleverTap.sharedInstance()?.recordChargedEventWithDetails(chargeDetails, andItems: [item1, item2, item3])
copy Copied
clevertap.event.push("Charged", {
    "Amount": 300,
    "Payment mode": "Credit Card",
    "Charged ID": 24052013, // important to avoid duplicate transactions due to network failure
    "Items": [
        {
            "Category": "Books",
            "Book name": "The Millionaire next door",
            "Quantity": 1
        },
        {
            "Category": "Books",
            "Book name": "Achieving inner zen",
            "Quantity": 1
        },
        {
            "Category": "Books",
            "Book name": "Chuck it, let's do it",
            "Quantity": 5
        }
    ]
});
copy Copied
Dictionary<string, object> chargeDetails = new Dictionary<string, object>();
chargeDetails.Add("Amount", 300);
chargeDetails.Add("Currency", "USD");
chargeDetails.Add("Payment mode", "Credit card");
chargeDetails.Add("Charged ID", 24052013); // important to avoid duplicate transactions due to network failure

Dictionary<string, object> item1 = new Dictionary<string, object>();
item1.Add("Category", "books");
item1.Add("Book name", "The Millionaire next door");
item1.Add("Quantity", 1);

Dictionary<string, object> item2 = new Dictionary<string, object>();
item2.Add("Category", "books");
item2.Add("Book name", "Achieving inner zen");
item2.Add("Quantity", 1);

Dictionary<string, object> item3 = new Dictionary<string, object>();
item3.Add("Category", "books");
item3.Add("Book name", "Chuck it, let's do it");
item3.Add("Quantity", 5);

List<Dictionary<string, object>> items = new List<Dictionary<string, object>>();
items.Add(item1);
items.Add(item2);
items.Add(item3);

CleverTapInstance.Event.PushCharged(chargeDetails, items);
copy Copied
Dictionary<string, object> chargeDetails = new Dictionary<string, object>();
chargeDetails.Add("Amount", 300);
chargeDetails.Add("Currency", "USD");
chargeDetails.Add("Payment mode", "Credit card");
chargeDetails.Add("Charged ID", 24052013); // important to avoid duplicate transactions due to network failure

Dictionary<string, object> item1 = new Dictionary<string, object>();
item1.Add("Category", "books");
item1.Add("Book name", "The Millionaire next door");
item1.Add("Quantity", 1);

Dictionary<string, object> item2 = new Dictionary<string, object>();
item2.Add("Category", "books");
item2.Add("Book name", "Achieving inner zen");
item2.Add("Quantity", 1);

Dictionary<string, object> item3 = new Dictionary<string, object>();
item3.Add("Category", "books");
item3.Add("Book name", "Chuck it, let's do it");
item3.Add("Quantity", 5);

List<Dictionary<string, object>> items = new List<Dictionary<string, object>>();
items.Add(item1);
items.Add(item2);
items.Add(item3);

CleverTapInstance.Event.PushCharged(chargeDetails, items);
copy Copied

Advantages of the Charged event

  • Helps you identify your customers, and how are they using your app or website
  • Run campaigns to reward loyal users or get lost customers back
  • Measure customer loyalty via running a cohort analysis on repeat purchases
  • Analyze paid campaign performance by total revenue earned
  • Get revenue insights like – total revenue, number of transactions, count of paying users and much more

Best Practices

Listed are some recommended best practices that you should keep in mind during event design –

Naming events

  • We recommend starting your integration with a max of 5 events that are critical to the success of your business
  • Use short event and property names if possible – you’ll thank us when analyzing events in the dashboard
  • Event names should match the action a user performs on your site. Example event names – “Viewed product”, “Added To cart”, “Video watched”, etc.
  • Whenever possible, use the same names across your mobile apps and websites
  • Group similar events with a common prefix – e.g. “Booking initiated”, “Booking dates selected”, “Booking room selected”, “Booking completed”

Do not do

  • Record broader events instead of granular ones. E.g. record a “Video watched” event with “Duration” as a property value, instead of three separate events like – “Video start”, “Video pause” and “Video end”
  • Recording every user action results in too many events, which will make it harder to find meaningful answers from the dashboard
  • Do not record screen loads or unloads, button clicks or form submissions. Instead, record user actions that are in-line with your business objectives.
  • Do not capture page views as events, or page URLs as event properties. You can get better insights on how people use your product than by the pages they visit

Things to note

  • It’s okay to have some events recorded specifically for your application or website as the flows might be different
  • If your purchase process is broken into multiple steps, record each step as a separate event for better funnel analysis
  • If you accept payments in multiple currencies, you can record it via event properties. However, in the amount field convert the incoming amount to a single currency value. This will simplify revenue and LTV analysis
  • Avoid storing user profile information like age, gender etc. as event properties. Store them as User Attributes instead

Platform Considerations

  • The maximum number of User Event types per app is 100. While the number might seem limiting, if used along side properties can help you record a lot more User Event data than it seems. The volume of events submitted per account across those event types is practically unlimited.
  • For each User Event recorded, the maximum number of Event Properties is limited to 16.
  • ‘Charged’ Event supports upto 16 Items values
  • Event property keys must be of type String and property values must be scalar values, i.e. String, Boolean, Integer, Float or a Date object.
  • User Event keys are limited to 32 characters in length.
  • User Event property values are limited to 40 bytes in length.
  • User Event are query-able for the past 365 days.

When you exceed the number of events being recorded, you can “discard” some events not being used anymore. To discard events Go to Dashboard → Settings → My Account → Events & Properties → Discard Event for that particular event.
Discarding events: Be careful, this action cannot be undone