User DocumentationDeveloper DocumentationPartner GuideWhat's New
User Documentation
Request DemoSign In

Events

Suggest Edits

Overview

Events track what individual actions users perform in your app or website. Some examples of events include a user launching an app, viewing a product, listening to a song, sharing a photo, making a purchase, or favoriting an item.

By tracking events in your app, you can better understand what users are doing. In CleverTap, you can analyze these events in many different ways, such as getting aggregating metrics of a specific event or measuring how a specific event type trends over time. You can also engage with your users based on these events by creating campaigns in CleverTap that are triggered by them.

898

Event Categories

CleverTap has two categories of events:

  • System events: Events recorded automatically after you integrate our SDK.
  • Custom events: Events you define and track with our SDK or API.

Event Properties

Events have details that describe the action taking place called properties.

For example, while recording the Product viewed event, you could also store event properties, such as product name, category, and price. Recording event properties will help you discover insights, such as which product category is more popular, and segment users based on which categories or price points they have viewed.

System Events

📘

Events Changelog

You can find information about the most recent changes to our existing system events or the introduction of new ones in our Events Changelog.

System events are events recorded automatically after you integrate our SDK.

Event Type

Description

How Event is Tracked

App Installed

The event is raised when the user launches the app for the first time

The event is raised when the user launches the app for the first time on any mobile device.

There are two cases when this event will be recorded multiple times for a single user. The first case is when a user installs your app, uninstalls it, and then reinstalls it. The second case is when a user clears your app's memory and relaunches it.

App Launched

This event is recorded every time a user launches your application.

There are two cases when this event will be recorded. The first case is a fresh app launch, which is when an app is launched from a killed state. The second case is when an app is brought to the foreground after 20 minutes of inactivity in the background.

App Uninstalled

This event is recorded when a user uninstalls your application.

This event is tracked by sending silent push notifications which is a type of notification that is not rendered on a user’s device. We send silent push notifications to your entire install base once every 24 hours to track uninstalls. For more information, refer to App Uninstall.

Web Session Started

This is a web entry event similar to the App launched event. This event refers to the event triggered when a user starts a session or engages with your website.

This event will be recorded in two cases: when a user opens a webpage and when a user reloads the browser after 20 minutes of inactivity.

UTM Visited

This event is tracked when a user clicks on a link from a marketing campaign that has a UTM parameter defined on it. This event is also tracked when a CleverTap-integrated attribution platform, such as Branch or Apsalar, sends this information to CleverTap.

The UTM Visited event is recorded for your marketing campaigns from external sources, such as Google Adwords or AdRoll.

Notification Sent

This event is tracked when a campaign message is sent to a user. This event is always recorded, even if the user does not open or click on the message. This event is recorded for email, mobile push, SMS and web push, campaigns. The Notification Sent event is available on the Event dashboard but it is not displayed on the User Profile.

The event is tracked when the notification is successfully sent from CleverTap to the communication channel you select for your campaign.

Notification FailedThis event captures the errors that occurred in the campaign.This event records campaign errors in CleverTap for user-level tracking and analysis. It enables our customers to track, analyze, and address campaign errors at the user level.

This event logs all types of errors for WhatsApp campaigns. However, only specific dispatch errors are currently recorded for other channels, such as Push and SMS. For detailed information on the specific dispatch errors included for these channels, contact your Customer Success Manager (CSM).

Note:
This event is retained for a year and captures dispatch and delivery errors. For detailed information on WhatsApp errors, refer to WhatsApp Error Stats.

Event Properties:


  • Campaign ID: It helps identify the specific campaign associated with the error.
  • Campaign Type: It indicates the type of campaign (for example, WhatsApp, SMS).
  • Error: It describes the title of the error observed in the campaign.
    Label: It denotes the specific label associated with the error.
  • Variant: It helps identify the errors for a specific campaign variant in case of A/B, split delivery, or multi-variant campaigns.


Note: This event is currently in private beta and can be enabled upon request. Contact your account manager if you need access to this event.

Notification Viewed

This event is tracked when a user views an email, in-app notification, or a web notification sent from CleverTap.

The CleverTap SDK recognizes when a notification sent via CleverTap is viewed by a user.

Notification Viewed is available for email, web push, in-app, web popup, and app inbox.

Important Properties:

  • Variant: String value containing an A/B testing campaign's variant name.

Notification Clicked

This event is tracked only when a user clicks on a campaign sent via CleverTap. You can track or create a Notification Clicked event for every UTM Visited event that is tracked by CleverTap and not any other provider.

There is no separate event storage required for the Notification Clicked event because it is derived from the UTM Visited event.

Recorded when a user clicks on a mobile push, in-app, email, web popup, or web push message sent via the CleverTap dashboard or through the campaign API.

The Android push notifications containing deep links to third-party apps are not tracked.

Important Properties:

  • Variant: String value containing an A/B testing campaign's variant name.
  • wzrk_c2a: String value containing the action button name of notification clicked events.
  • button_id: Visible only when the Notification Clicked event is tracked for button clicks associated with the Image Interstitial template.

The "Notification Clicked" event is triggered only for CleverTap BSP users if Click tracking is enabled when creating WhatsApp campaigns

Push Impressions

This event is tracked when a push notification sent from CleverTap is delivered on a user’s device. The funnels on the Push campaign statistics page reflects the count for this event.

After the toggle for Push Impressions is turned on/setup from settings, the CleverTap SDK starts recording an event whenever a push notification sent via CleverTap is delivered to the user’s device.

App Version Changed

This event is raised when a user’s current app version is different from the user’s previous app version.

This event is tracked when the CT App version system property differs from one App Launched event to another.

Notification Replied

This event is recorded when a user replies to a WhatsApp message or an SMS campaign.

This event is raised when the brand receives a reply from the user.

Properties:

  • Incoming Message Type: Represents the type of message received (text, image, document, etc.)

  • Channel: String value that represents the medium of the incoming message.

  • Incoming text: String value that represents the incoming message. In the case of an SMS campaign, it includes the reply message sent by the SMS recipient. The maximum length of the message is set to 512 characters.

  • Incoming Media URL: String value that represents the URL of the media included in the message.

  • Destination WABA number: String value that represents the WABA number to which the message was sent.

  • Source WABA number: String value that represents the WABA number from which the user replied.

  • Campaign ID: String value that represents the original campaign ID to which the user has replied

  • Provider: In the case of WhatsApp campaign, it represents the source WABA number provider. In the case of an SMS campaign, it represents the service through which the campaign is sent.

  • Lat: Float value that represents the latitude of the particular location.

  • Long: Float value that represents the longitude of the particular location.

Reply Sent

This event is recorded when an agent (CleverTap user) replies to a message from the end user.

This event is raised against the user profile of the end user.

State Transitioned

This event is recorded for lifecycle optimizer when a user transitions from one stage to another.

This event is raised whenever a user transitions from one state to another or from unmapped to one of the states in the lifecycle optimization framework. It is meant for internal usage at CleverTap and therefore, unavailable for querying.

Session Concluded

This event is recorded to mark the end of a session. Session tracking must be enabled for the event to be tracked.

This event is raised when there is 20 minutes of inactivity after an event is raised for a user.

Geocluster Entered

This event is recorded to mark when a device enters a geofence.

The event will only be applicable for customers who have the geofence feature enabled for them.

Properties:

  1. Cluster ID
  2. Cluster name
  3. Geofence ID

The event is tracked whenever a device enters a geofence.

Geocluster Exited

This event is recorded to mark when a device exits a geofence.

The event will only be applicable for customers who have the geofence feature enabled for them.

Properties:

  1. Cluster ID
  2. Cluster name
  3. Geofence ID

The event is tracked whenever a device exits a geofence.

Channel Unsubscribed

This event is raised only for Email and Push campaigns. It is raised when end-users unsubscribe from future emails and push notifications. It is also raised when the user resubscribes for the email campaigns

Properties:

  1. Campaign ID: This is the ID of
    the campaign from which user are updating subscriptions.
    Campaign Type: Currently only present for email and push campaigns.
  2. Group: Group name from which the user unsubscribed/resubscribed.
  3. Identity: The user identity/email address.
  4. Variant
  5. Type: Valid values are bounced, dropped, and spam. Email IDs that bounce, drop, or are marked as spam are opted out of future emails.
  6. Subscription Type: Account level and Profile level.
    • Profile Level: The specific profile is opted out for all email campaigns in the future until they opt in again.
    • Account Level: The specific profile and email address are opted out of all email campaigns. Even if other profiles have that email address, they will not be sent emails in the future because that email address has been unsubscribed at the account level.
  7. Resubscribed: The value is true if the user has resubscribed, or else the value will be false.
  8. Reason: Currently, present for email campaigns only. It is the same reason that was given by the email provider for the type of error. For example: "smtp;550 5.1.1 The email account that you tried to reach does not exist. Please try double-checking the recipient's email address for typos or unnecessary spaces."
Channel SubscribedThis event is raised when the user subscribes to a push notification channel for devices with Android OS version 13 and above. In the case of devices on Android 13 and above, the event is raised when the user gives permission. In the case of devices on Android 12, the event is raised when the user resubscribes for the push campaigns.

Properties:

  • Source: Indicates if the event is raised through a device, application, or API.
  • Channel: Indicates the channel for which the user has subscribed i.e. Push Notification.
  • App Version: Indicates the app version from which the event is raised.
  • SDK Version: Indicates the SDK version installed on the device.
Notification DeliveredThis is an event raised only for WhatsApp and SMS campaigns.
  • In the case of WhatsApp, it is raised when the provider confirms that the notification has reached the end user (double-tick of WhatsApp).
  • In the case of SMS campaigns, it is raised when the notification is delivered to the end user, and CleverTap receives the callback. It includes the Provider event property, a string value that represents the service through which the campaign is sent. For example, Twilio.
    • App UpgradedThis event is raised when a user’s current app version is different from the user’s previous app version.This event is tracked when the CT App version system property for an app launch is different from the next app launch.
    Session ConcludedThis event is recorded to mark the end of a session. Session tracking must be enabled for the event to be tracked.This event is raised when there is 20 minutes of inactivity after an event is raised for a user.
    State TransitionedThis is an event raised only for Lifecycle Optimizer.This event is recorded when a user transitions from one stage to another.This event is raised whenever a user is assigned a state or there is a transition from one state to another. It is meant for internal usage at CleverTap and therefore, unavailable for querying.
    AB Experiment RenderedThis event indicates that the variant has reached the device.Event is raised when you are using the _Product A/B Tests _feature.
    AB Experiment Rolled OutThis event is raised when the winner variant is sent to all devices.Event is raised when you are using the _Product A/B Tests _feature.
    AB Experiment StoppedThis event is raised when experiment was stopped.Event is raised when you are using the _Product A/B Tests _feature.
    AB Experiment DisqualifiedThis event is raised when the device is disqualified.Event is raised when you are using the _Product A/B Tests _feature.
    Partner SyncAn event raised for each user profile that is part of cohorts imported from partners like Mixpanel.The Partner Sync event is raised every time CleverTap receives a cohort sync request from partners like Mixpanel. This event is raised for each user in the cohort sync.

    Debug Events

    Debug events are events recorded automatically after you integrate our SDK. These events are raised at certain lifecycle stages in your integration and help you track and manage your integration. These events are available on any profile page and Find People page by adding a parameter to the end of the URL ?showDebugEvents=true.

    Event Name

    Description

    When is it raised

    Identity Set

    This debug event is raised when a new user is identified on a customer’s app or an identified user pushes another identity.

    This event monitors the status and data points that are important for the identification and engagement of users. This event is for monitoring and debugging only.

    Identity Reset

    This debug event is raised when a profile is demerged (after demerged, a new profile for every device is created and identities are dropped) either from the dashboard (click on the Profile page to reset identities) or through the Demerge Profile API.

    It monitors the reset of identities and handles unnecessary merges. This event is used for monitoring and debugging only.

    Identity Error

    This debug event is raised when an existing identity is associated incorrectly with another identity. The former identity is now declared as invalid for the latter's profile.

    This event is for monitoring and debugging when identity merges are invalid.

    Reachable By

    This debug event is raised when a user becomes reachable by a communication channel such as SMS, email, mobile push, or when there are changes to the existing communication channel.

    Tracked for a profile when:

    • Push token is added/changed.
    • Email ID is added/changed.
    • Phone number is added/changed.

    Push Unregistered

    This event tracks the removal of a mobile push token. It is also raised when FCM returns a 404 Unregistered error for stale tokens from devices that have not connected to FCM for 270 days or for users who uninstall the app.

    This event is raised when an existing mobile push token is removed for a profile.

    Tracked for a profile when:

    • A user logs out of the device, and another user logs in. Applicable only if the onUserLogin() method is implemented.

    • When a push token is removed using the pushFcmRegisterationId("token",false) method. Applicable only for Android.

    • FCM returns a 404 Unregistered error for stale tokens from devices that have not connected to FCM for 270 days or for users who have uninstalled the app.

    Custom Events

    Custom events are events you define and track with our SDK or API. For more information, refer to the Events in the developer documentation.

    Charged Event

    CleverTap also records transactions or purchases using a special event called Charged. Clevertap enriches this special event with additional information such as items sold, their categories, transaction amount, transaction ID, and information about your users. Recording a purchase against a user marks them as a customer in CleverTap and enables you to compare your funnel reports between customers and non-customers.

    When recording customer purchases, you can also record the following:

    • Items Sold
      You must use the Items collection to record a list of items sold. Along with the product name, you can add properties such as size, color, category, etc.

    • Transaction Amount
      The transaction total or subscription charge must be recorded in an event property called Amount.

    For more information about recording a Charged event, refer to Events under developer documentation.

    Advantages of the Charged Event

    The following are the advantages of Charged event:

    • Helps you identify your customers and how they are 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

    Charged Event Personalization

    You can personalize the message for customers who purchase multiple items in a single transaction. You can do so by using liquid tags from the CleverTap dashboard, as shown in the following sample codes:

    • Using for Loops in Liquid Tags 
    //Iterates over Items array in Event and displays the names of items within the "Event.Items" array, with a default value of "NA" for items that do not have a defined name property
{% for item in Event.Items %}
{{item.name | default: "NA"}}
{% endfor %}
    • Using Manual Indexing in Liquid Tags 
    //Iterates from 0 to 50 and displays the names of the items within the "Event.Items" array, as long as the index is within the valid range.
{% for i in (0..50) %}
{% if i < Event.Items.size %} 
{{ Event.Items[i].name | default: "NA" }} //It uses a default value of "NA" for items without a defined name property.
{% endif %}
{% endfor %}

    Event.items is a custom array property that you can use to store additional information about items associated with an event. It allows you to include item-specific details when tracking events. For example, if an event called "Charged" represents a user making a purchase, you can use the Charged.Items array to store information about the specific items purchased within that event. Each item in the array can have its own properties, such as name, price, quantity, and so.

    You can personalize the message for any number of items in the Event.items array. For example, you want to send an email including order details to the customers who bought three books from your e-commerce website. The Event.items array, in this case, would include three items, and you can send a personalized message for all three items.

    Charged Event Personalization

    Charged Event Personalization

    In the case of manual indexing, you can ensure that the index is smaller than the size of the Items array using Event.Items.size. If the index value exceeds the size of the Items array, the message is NOT dispatched and is marked against errors.

    📘

    Charged Event Personalization for App Inbox Campaigns

    • In the case of App Inbox campaigns, event personalization for Charged.Items is not enabled.
    • However, if you use event personalization with Charged.Items, the default values for the items are displayed in the case of App Inbox campaigns.
    • If you use event personalization with Charged.Items when creating a combination of Push Notification and App Inbox campaigns, the personalized values for the items are displayed for Push and default values are displayed for App Inbox.

    Event Data Types

    CleverTap supports the following data types:

    • String
    • Integer
    • Float
    • Boolean
    • Mixed

    You can use an array only with the Charged event. All others will return an incorrect data type if using an array.

    Event Metadata Recorded Automatically

    For every recorded event, 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 referring site and the source of the user visit if it was from an external source.

    In addition, CleverTap keeps the user profiles updated with the latest:

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

    System Properties

    CleverTap tracks the following system properties automatically from the mobile SDK. All the system properties are prefixed by CT indicating that they are provided by CleverTap.

    The following properties are tracked automatically on all events:

    System Property

    Description

    CT App Version

    This is the current version of your application installed on the user device.

    CT Latitude

    The user location identified by the latitude.

    CT Longitude

    The user location identified by the longitude.

    CT Source

    The source of the event.

    For example, the event may originate from a Mobile SDK or an API.

    All possible values:

    • Mobile (Mobile SDK)
    • MobileWeb (Web SDK)
    • Web (Web SDK)
    • API
    • segment
    • appsflyer
    • apsalar
    • branch
    • tune
    • System (for events generated by CleverTap)

    The following properties are available on the App Launched event:

    System Property

    Description

    CT App Version

    This is the current version of your application installed on the user device.

    CT Latitude

    The user location identified by the latitude.

    CT Longitude

    The user location identified by the longitude.

    CT OS Version

    The operating system of the device.
    For example, 1.0.0.

    CT SDK Version

    The CleverTap SDK version. For example, 30501.

    CT Network Carrier

    The network carrier of the device.
    For example, AT&T, Vodafone.

    CT Network Type

    The network type of the device.
    For example, 4G.

    CT Connected To WiFi

    Indicates if the device is connected to the Wi-FI.

    CT Bluetooth Version

    The Bluetooth version of the device.

    CT Bluetooth Enabled

    Indicates if Bluetooth is enabled on the device.

    CT Source

    The source of the event.

    For example, the event may originate from a Mobile SDK or an API.

    All possible values:

    • Mobile (Mobile SDK)
    • MobileWeb (Web SDK)
    • Web (Web SDK)
    • API
    • segment
    • appsflyer
    • apsalar
    • branch
    • tune
    • System (for events generated by CleverTap)

    📘

    Latitude and Longitude

    The system properties latitude and longitude are captured and sent from the SDK only if the user gives consent on your app.

    Updated 9 days ago