Introduction

Events refers to the actions your users perform on your app or website eg. purchase, add to wishlist, search etc. Events also includes other actions such as app install, app uninstall, email open, email click etc. Each such event has attributes attached to it that captures where and when the event happened (eg. event time, location, device) and also describes the event in detail (eg. for Purchase event - item category, item price etc.). You can use event-related information to understand your users better, segment them and personalize your campaigns.

Before you start the integration process, please ensure that you are consistent with the usage of event names and the attributes attached to each, across all platforms such as, Android, iOS and Website. We recommend that you create an excel sheet where you can list down all the events you want to track along with their corresponding attributes and data-types. Data-types, once defined, cannot be changed later. If WebEngage receives data in a different datatype from what was first defined, it will not be able to record this data.

Types of Events

Events on WebEngage are of 3 types: System, Custom and Campaign.

System Events

These events (except User Login, User Logout) are automatically captured by WebEngage as soon as the SDK integration is done. Here's a complete list of all the system events defined by WebEngage:

Event Name on Dashboard
Event Name at Backend
Description

App Installed

app_installed

When the app gets installed

App Upgraded

app_upgraded

When the app is upgraded

App Crashed

app_crashed

When the app crashes

App Uninstalled

app_uninstalled

When app is uninstalled

User Login

user_logged_in

Whenever you call the login function on user login, signup etc.

User Logout

user_logged_out

Whenever you call the logout function

Session Started

user_session_started

Whenever a new session is started. Please see the definition of session below.

How does WebEngage define session?
For websites, session time = the time for which the user is active on your website (activity can mean any of the following - performing events like search, add to cart etc., same webpage being refreshed/reloaded, a new webpage being opened). If the user is inactive for 30 minutes then the session ends. The inactivity here can mean any of the following - (1) User is on your website but is inactive (see definition of active above), (2) User is on a different website in another tab, and (3) User is switching between tabs from another website to your website but is not performing any activity on your website. In other words, this means that session time out duration for websites is 30 minutes.

For mobile apps (iOS and Android), session time = the time for which the app is open (or in other words, app is in foreground). If the user backgrounds your app (to open another app) and doesn’t foreground your app within 15 seconds, the session will end. Or in other words, the session time out duration for apps is 15 seconds.

Custom Events

These event are sent by you to WebEngage, based on the actions performed by your users, on your mobile app and/or website. Some examples of these events are: Purchased, Category Viewed, Searched etc. You will be able to define events according to the needs and nature of your business.

We recommend that you track the following events based on the industry that your business is in: E-commerce, Travel, Game apps, BFSI.

Campaign Events

These events are automatically captured by WebEngage, based on the actions your users perform on the campaigns they receive through WebEngage. Here's a list of all the campaign events available on WebEngage.

Event Name on Dashboard
Event Name at Backend
Description

Campaign Conversion

goal_accomplish

When a user completes the conversion event attached to a campaign

GCM/APNs Registered

gcm_registered

When a device is registered successfully to receive push notifications

APNs Registration Failed

apns_registration_failed

When device fails to register to receive push notifications

Push (Mobile) Sent

gcm_notification_response

When mobile push notification is sent by WebEngage

Push (Web & Mobile) Queued

push_notification_queued

When a mobile push or web push campaign is queued for delivery by WebEngage to GCM or our VAPID server for any of these reasons

Push (Web) Accepted

push_notification_accepted

When a web push campaign is forwarded by WebEngage for delivery by our VAPID server

Push (Web & Mobile) Rejected

push_notification_rejected

When a mobile push or web push campaign is rejected by WebEngage and is not forwarded to GCM (for mobile push) or our VAPID server (for web push)

Push (Mobile) Received

push_notification_received

When a device receives a mobile push notification successfully

Push (Web & Mobile) Dismiss

push_notification_close

When a user dismisses a mobile push or web push notification

Push (Web & Mobile) Impression

push_notification_view

When a user views a mobile push or web push notification

Push (Web & Mobile) Click

push_notification_click

When a user clicks a mobile push or web push notification

Push (Mobile) Rating Submitted

push_notification_rating_submitted

When a user submits a rating for a mobile push notification rating campaign

Push (Mobile) Carousel Item Viewed

push_notification_item_view

When a user views items in a mobile push notification carousel campaign

Push (Web) Registered

push_notification_registered

When a user successfully subscribes to web push after clicking “Allow” on native browser prompt

Push (Web) Unregistered

push_notification_unregistered

Please see the details here

Notification (On-site & In-app) Impression

notification_view

When a user views an on-site notification or in-app notification

Notification (On-site & In-app) Close

notification_close

When a user closes an on-site notification or in-app notification

Notification (On-site & In-app) Click

notification_click

When a user clicks on an on-site notification or in-app notification

On-site Feedback View

feedback_view

When a user views an on-site feedback

On-site Feedback Close

feedback_close

When a user closes an on-site feedback

On-site Feedback Submit

feedback_submit

When a user submits an on-site feedback

On-site Survey View

survey_view

When a user views an on-site survey

On-site Survey Close

survey_close

When a user closes an on-site survey

On-site Survey Complete

survey_complete

When a user completes an on-site survey

On-site Survey Submit

survey_submit

When a user submits an on-site survey

SMS Queued

sms_queued

When a SMS is queued for delivery by WebEngage to the SSP for any of these reasons

SMS Accepted

sms_accepted

When a SSP successfully accepts the SMS sent by WebEngage to the SSP for delivery to the customer

SMS Rejected

sms_rejected

When a SSP rejects the SMS sent by WebEngage to the SSP for delivery to the customer

SMS Sent

sms_sent

When a SSP successfully delivers the SMS to the customer

SMS Failed

sms_failed

When a SMS fails to deliver as reported by the SSP

SMS Click

sms_click

When a user clicks on a link in a SMS

Email Queued

email_queued

When an email is queued for delivery by WebEngage to the ESP for any of these reasons

Email Accepted

email_accepted

When a ESP successfully accepts the email sent by WebEngage to the ESP for delivery to the customer

Email Rejected

email_rejected

When a ESP rejects the email sent by WebEngage to the ESP for delivery to the customer

Email Processed

email_processed

When a ESP has received the email sent by WebEngage to the ESP for delivery to the customer

Email Sent

email_sent

When a ESP has sent the email to the customer. Subsequently, the message may get delivered or may not (because of hard-bounces and soft-bounces).

Email Bounced

email_bounce

When an email gets bounced as reported by the ESP

Email Delivered

email_delivered

When the email is delivered as reported by the ESP

Email Complaint

email_complaint

When a user or an email client like Gmail complains about the email (in case of phishing etc.)

Email Abuse Report

email_abusereport

When a user marks an email as Spam

Email Resubscribe

email_resubscribe

When a user subscribes again to receive email campaigns

Email Unsubscribe

email_unsubscribe

When a user unsubscribes from all email campaigns

Email Spam Report

email_spam

When a user marks an email as Spam

Email Open

email_open

When a user opens an email

Email Click

email_click

When a user clicks on a link in an email

Web Push Subscribe Viewed

push_notification_window_view

When a user views the native browser prompt to subscribe to web push notifications

Web Push Subscribe Denied

push_notification_window_denied

When a user clicks "Deny" or "Block" on the native browser prompt to not subscribe to web push notifications

Web Push Subscribe Successful

push_notification_window_allowed

When a user clicks "Allow" on the native browser prompt to subscribe to web push notifications

Web Push Subscribe Notification Viewed

push_notification_prompt_view

When a user views the on-site notification prompt to subscribe to web push notifications

Web Push Subscribe Notification Denied

push_notification_prompt_denied

When a user clicks "Deny" or "Block" or "Not Allow" on the on-site notification prompt to not subscribe to web push notifications

Web Push Subscribe Notification Allowed

push_notification_prompt_allowed

When a user clicks "Allow" on the on-site notification prompt to subscribe to web push notifications. This opens the native browser prompt that the user has to click "Allow" on to actually subscribe to receive web push notifications

What is the Push (Web) Unregistered event?

When user revokes access for receiving web push from the browser settings or while sending the web push, server returns a token not present error. Also, when a user logs out, we send this event (Push (Web) Unregistered) for the previously logged-in user and we send Push (Web) Registered for the new anonymous ID created.

Event Attributes

All events have attributes attached to them that capture its details. Eg. Attributes of a purchase event would include the time of event, device on which the event happened, location from where the event happened, details of the item purchased etc.
Attributes are of 2 types: System and Custom. These attributes are applicable to different event types, as follows:

  • System Events: Only have system attributes
  • Custom Events: Have both system and custom attributes
  • Campaign Events: Only have system attributes

System Attributes

These are defined by WebEngage and are automatically captured as and when an event happens. You cannot overwrite these values or modify them in any way.

Here’s a complete list of system attributes defined by WebEngage:

Name
Type
Description

Event Time

DateTime

Time when the event occurred in ISO Format

Country

String

Country where the event occurred

City

String

City where the event occurred

Browser Name

String

Name of the browser on which the event occurred

OS Name

String

Name of the OS on which the event occurred

Device Manufacturer

String

Name of the manufacturer of the device on which the event occurred

Device Model

String

Device model on which the event occurred

Carrier

String

The device cellular network on which the event occurred

App Version

String

The version of the app on which the event occurred

App ID

String

The ID of the app on which the event occurred

Platform

String

The platform on which the event occurred - one of Android, iOS, Website

Channel

String

The channel (Direct, Organic Search, Social etc.) that resulted in the occurrence of the event

Campaign Source

String

The UTM source of the marketing campaign that resulted in the occurrence of the event

Campaign Medium

String

The UTM medium of the marketing campaign that resulted in the occurrence of the event

Campaign Name

String

The UTM name of the marketing campaign that resulted in the occurrence of the event

Page URL

String

The page URL on which the event occurred (in case of website)

Screen Name

String

The screen name on which the event occurred (in case of mobile app)

Campaign ID

String

The ID of a campaign that was sent through WebEngage

Variation ID

String

The ID of the variation in a campaign that was sent through WebEngage

Journey ID

String

The ID of the journey in WebEngage that the campaign is a part of

Custom Attributes

You can define custom attributes of an event depending on your business needs. For example, a Purchase event could have the following attributes: Item Name, Item Price, Currency, Category Name, Category Code.

We recommend the following custom events and event attributes based on the industry that your business is in: E-commerce, Travel, Game apps, BFSI.

Please take note of the following limitations when you’re creating new custom attributes:

  • Values of an attribute can only be of one of the following data types: Boolean, Number, String, Date, Map and Array.
  • A customer can have a maximum of 25 custom attributes per data type for the following data types: Boolean, Number, String, Date (i.e. 25 custom attributes of Number data type, 25 custom attributes of String data type etc.).
  • A custom event can have as many attributes of Map and Array data types as you would like with the limitation that all the values together occupy a maximum space of 16KB.
  • The maximum length of an event name is 50 characters.
  • The maximum length of a String data type for an attribute is 1000 characters.
  • The maximum length of an attribute name is 50 characters.
  • The name of your event or event attribute should not begin with we_.

Tracking Events

System and campaign events are tracked automatically by WebEngage. You can send Custom events to WebEngage by calling the respective SDK functions - Website, Android, iOS

Events


Suggested Edits are limited on API Reference Pages

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