Tracking Events

📘

Must Read

Before moving onto Tracking Events, it will be most helpful to get a better grasp of System & Custom events and their respective attributes. It will help you to understand the workings of Tracking Events much better.
Click here to view Custom Event Templates to get a good understanding.

NVECTA immediately begins tracking once you integrate the SDK. These are referred to as System Events, and they start tracking common user interactions with your app and also your campaigns. Click here to view the System Events that we automatically track for you.

You can create your Custom Events that will track your user interactions, important to your business growth. You can further break down each Custom Event into more Event Attributes as:

• Quantity
• Price
• Category

Granular data like this will enable you to engage more users through personalised and contextual campaigns through Omni-channels or all channels of engagement.

Tracking Custom Events for the Web

You can track Custom Events through our Web SDK. You can also track associated event attributes with it if you want to, as shown below:

nv('event', EVENT_NAME, EVENT_ATTRIBUTES, LIFETIME_VALUE, SCOPE);

EVENT_NAME (string)
USAGE: To name events like sign_up, add_to_cart, purchase, etc.

• It is a string value.
• Use only Alpha Numerics.
• You can use white spaces.
• You can use underscore '_.'

EVENT_ATTRIBUTES (JSON object)
USAGE: These attributes are associated with an Event

Attribute values are passed in the form of JavaScript:

• Strings
• Booleans
• Numbers
• Date Attribute values are written using JavaScript date objects

📘

Important:

Attribute Names should contain only alpha-numerics, white spaces or '_' ; No other special characters are allowed. Recommended names - 'category', 'price_usd'

LIFETIME_VALUE (integer)
USAGE: For awarding a score point to the user, like: 10 or 100

SCOPE (integer)

Tracking Event Attributes

This is how you can track Custom Event Attributes for a Custom Event:

//example 1
nv('event', "Added To Cart", {
    "Currency"   : "USD",
    "Discounted" : true,
    "Items": [
        {
            "Product ID"        : 137,
            "Product"           : "Givenchy Pour Homme Cologne",
            "Product_url"       : "https://example.com/products/givenchy-pour-homme-cologne",
            "Product_image_url" : "https://example.com/images/givenchy-pour-homme-cologne.jpg",
            "Category"          : "Fragrance",
            "Price"             : 89.70,
            "Quantity"          : 1
        }
    ]
}, 100, 1);

//example 2
nv('event', "Order Placed", {
    "Amount"         : 807.99,
    "Delivery Date"  : "2017-01-09T00:00:00.000Z",
    "Delivery City"  : "New York",
    "Delivery ZIP"   : "10001",
    "Coupon Applied" : "BOGO17",
    "Items": [
        {
            "SKU"               : "UHUH789",
            "Name"              : "CK Jeans",
            "Product_url"       : "https://example.com/products/ck-jeans",
            "Product_image_url" : "https://example.com/images/ck-jeans.jpg",
            "Price"             : 300.09,
            "Size"              : "L"
        },
        {
            "SKU"               : "FBHG756",
            "Name"              : "Hugo Boss Jacket",
            "Product_url"       : "https://example.com/products/hugo-boss-jacket",
            "Product_image_url" : "https://example.com/images/hugo-boss-jacket.jpg",
            "Price"             : 507.90,
            "Size"              : "L"
        }
    ]
}, 100, 1);

Add users and events at the same time

More often than not, there exists a requirement to simultaneously track users and the events they perform. Since, if the users and the actions performed by them are tracked independently, then there are chances that the tracked events will not get tagged with their respective users, primarily because there exists a 'time gap' between users getting tracked and then subsequently getting registered within the software's database.

To ensure that events always get mapped with their respective users, we created a new function through which both users and their corresponding actions get registered concurrently within the database. This new function, namely UserEvent, comes into effect exclusively when the tracked data of both the users and the events they performed is made available or catered to.

The syntax of the UserEvent function consolidates the functionality of the individual User and Event functions within a single function:

nv('userevent', [USER_IDENTIFIERS, USER_ATTRIBUTES, EVENT_NAME, EVENT_ATTRIBUTES]);

Example

nv('userevent', [
  {                                        // USER_IDENTIFIERS
    userID: 'XYZ4410',
    email: '[email protected]'
  },
  {                                        // USER_ATTRIBUTES
    name: 'John Doe',
    age: 28,
    gender: 'Male',
    city: 'Mumbai'
  },
  'Signed Up',                             // EVENT_NAME
  {                                        // EVENT_ATTRIBUTES
    "Signup Method": "Email",
    "Referral Source": "Google Ads",
    "Plan Selected": "Free Trial",
  },
  100,                                     // LIFETIME_VALUE
  1                                        // SCOPE (1 = track every time)
]);

Important points to note about the UserEvent function

• All the data points are elements of an array in the UserEvent function.
• In the case of the UserEvent function, the validation and processing of both the tracked user data and the corresponding event data, will work in the same manner as it does in the case of the existing User and Event functions.
• Within the UserEvent function, if there exist certain issue(s) in the validation and processing of the tracked user data, then the events performed by the user won't trigger i.e, the tracked event data associated with the user will not get processed either, even if it is error-free and faultless (capable of being processed).
• However, if the user data gets processed successfully i.e, the user gets registered within the software's database, but there exist certain issue(s) in the processing of the tracked event data pertaining to the registered user, then the user will remain registered within the database and his/her faulty event data will get discarded or in other words, the erroneous events performed by him/her won't trigger.

📘

Note

For the function to operate, it is mandatory to provide it with two important pieces of datum viz. the USER_ID and the EVENT_NAME. The remaining data points within the array of the UserEvent function are optional. In short, it isn't mandatory to provide them since they aren't necessarily required for the function to work as intended.

Guidelines

• Event names are case-sensitive and must be under 255 characters in length.
• Event names should not contain any special characters except space, underscore, or hyphen.
• Event attribute names are also case-sensitive and must be under 50 characters in length.
• String attribute values must be under 255 characters (255 bytes) in length.
• Each event can have up to 255 properties.
• Custom event attributes support the following data types, each with its own per-event attribute limit (i.e., the maximum number of attributes of that type you can include on a single event):
  • String: up to 200 attributes
  • Number: up to 100 attributes
  • Boolean: up to 20 attributes
  • Date (including Timestamp): up to 20 attributes
  • Object: up to 20 attributes
  • Array of Objects: up to 5 attributes
• Type locking: The first value sent for an attribute establishes its data type. If you later send a different type (e.g., quantity: "five" after sending quantity: 5), those mismatched values will not flow to your NotifyVisitors dashboard. In such cases, introduce a new attribute (e.g., quantity_v2) with the correct type — do not change the original.
• Use snake_case for event names and property names (e.g., order_completed, signup_type). Names are case-sensitive and hard to rename later, so choose a durable naming scheme from the start.
• The integration code loads and initialises the NotifyVisitors SDK asynchronously, so that it does not affect the page load time of your website.
• For a detailed breakdown of data types, limits, and naming conventions, refer to the Data Structure guide.