What are Events?

Any action your customers perform on your website, product, or app is an event. For example, in a customer journey where they get an email about a sale which ends with them making the purchase and completing the feedback survey, you can define the following events: opening emails, any clicks within emails, clicking buttons on your site, adding the products to a wishlist or a cart, making the purchase, and submitting a form.


Whenever an event occurs, an attribute will be attached to these events, giving more context. For example,

  • what device were they using
  • what operating system were they using
  • when did the event happen
  • what time and timezone were they in


You can also collect specific information to understand your customers better. With this understanding, you can offer personalized content relatable to them with better segmentation in future customer journeys.


What are custom events?

There are two types of events that are captured.

  • Default events: Default events are captured automatically, such as customer email
  • Custom events: Custom events are not captured automatically but need to be set up specifically for your use cases, such as cart abandonment, along with the attributes, such as product URLs, categories, and more.


Note: This process of tracking events on your website or your webapp requires some level of understanding in platforms such as Java, JS, Android & IOS, Webapps, etc.

Please proceed if you are comfortable with technical terminologies, if not, please work with your developers.


Defining Events

Before you begin, we recommend you note down all the different events you would like to track along with their attributes & Datatypes. You cannot change the datatypes that you define. Make sure of your definitions before starting. Similarly, data will not be recorded in customer journeys if the datatype received is not the same as it was defined in the beginning.


Here is a list of base attributes for your reference. These base attributes will be captured automatically whenever an event occurs on your webpage/web apps. Users cannot modify or edit these attributes in any way.


Base attributes (Table 1)

Name
Type
Description
event_name
string(50)
All the system event names
(email_sent,email_delivered,email_subscribed,email_unsubscribed,email_bounced,email_opened,email_clicked,journey_entered,journey_exited,page_viewed,form_submitted)
event_category
enum
All the system category(email, journey, web, form)
event_type
enum
System events and Custom events
org_id (account_id)
long
Org ID/Account ID associated with the user
contact_id
long
Contact ID associated with the user
event_time (created_at)
datetime
Event occurred time



System events and Custom events

System Events

System events are automatically captured and are added alongside all the events performed by the user in the Journey workflow. Bulk campaigns also will be captured. System events can be categorized into these four categories:


  1. Email Events 
  2. Journey Events
  3. Web Events 
  4. Form Events


1. Email Events



Table 1.1

EVENT CATEGORY
EVENT NAME
Email
Email Sent
Email Delivered
Email Opened
Email Clicked
Email Bounced
Email Unsubscribed
Email Subscribed


Email events attributes

Email event attributes are captured as part of the email events (listed in Table 1.1). These are saved along with any other attributes that are captured (listed in Table 1)


Table 1.2

subscription_id
The ID of the subscription
campaign_id
The ID of the campaign that was sent through Freshmarketer
journey_id
The ID of the journey sent through Freshmarketer that the campaign belongs to
journey_state_id
The ID of the journey status that was sent through Freshmarketer
email_event_id
The ID of the email which was part of the campaign


2. Journey Events



Table 2.1

EVENT CATEGORYEVENT NAME
JourneyJourney entered
Journey exited


Journey event attributes

Journey event attributes are captured as part of the journey events (listed in Table 2.1). These are saved along with any other attributes that are captured (listed in Table 1)


Table 2.2

journey_id
The ID of the journey sent through Freshmarketer that the campaign belongs to
journey_state_id
The status ID (Active, Draft, Stopped) of the journey that was sent through Freshmarketer


3. Web Events



Table 3.1

EVENT CATEGORYEVENT NAME
WebPage visit
Custom events



Web event attributes

Web event attributes are captured as part of the journey events (listed in Table 3.1). These are saved along with any other attributes that are captured (listed in Table 1)


Table 3.2

visitor_id
string (100)
The ID of the user
ipaddress
string (100)
The IP address of the user
browser_name
string (100)
Name of the browser in which event captured
city
string (255)
Name of the city where the event occurred
state
string(255)
Name of the state where the event occurred
country_code
string(5)
(iso code) Country code where the event occurred
medium
string(255)
UTM medium of the campaign in which event captured
referrer
string
Referrer of the event 
query_params(incl utm)
string(255)
Query parameter in the referrer URL with UTM 
domain
string(255)
Name of the domain URL on which event occurred
url
string
Page URL on which event occurred
url_path
string
URL path on which event occurred
OS 
string
Name of the OS on which event occurred


4. Form Events

EVENT CATEGORY
EVENT NAME
FORM
Form Submitted

Custom Events

Custom events are events that you can define and share with Freshchat to track events that are specific to your business. To set up custom events, you will need to setup the Associate visitor API and the Custom event API.

Let's look at custom events with the following example:


Associate Visitor API

In the above screenshot, ‘johnny.depp’ is an ANONYMOUS user who visited the Freshmarketer pricing page “https://www.freshworks.com/marketing-automation/pricing”. By using our JS API FM.associateVisitor(“email”) we are associating the anonymous user to their email contact.


Note: The above API will not create a contact if it is not already present in your account.
  • Rest API: 
curl -XPOST -H "fm-token:jrr3g04b0atvta4tmghbguhgugvd03r9n8v7eon7mv1b7qa" 'http://<domain>.freshmarketer.com/mas/api/v1/contacts/associate-visitor' -d '{"visitor_id": "1564408766806r0.8685208684454182", "email": "[email protected]"}'
Note: The above API will create a contact if it is not already present in your account.


Custom Events API
  • Frontend API
FM.trackCustomEvent("Added to cart",
{
"email": "[email protected]",
"price": 100.21,
"currency": "USD",
"is_mobile_transaction": true,
"return date": "2019-12-30"
});
  • Rest API
curl -XPOST 'https://<domain>.freshmarketer.com/mas/api/v1/[email protected]&event_name=signup_from_social' -d'{"price": 1000, "currency": "USD", "product-name": "Amazon Fire Stick", "user_id": "1010303"}' -H "Content-Type: application/json"
curl -XPOST 'https://<domain>.freshmarketer.com/mas/api/v1/[email protected]&event_name=signup_from_social' -d'{"price": 1000, "currency": "USD", "product-name": "Amazon Fire Stick", "user_id": "1010303"}' -H "Content-Type: application/json"


Date formats supported:

1. "yyyy-MM-dd";

2. "yyyy-MM-dd HH:mm:ssZ";

3. "yyyy-MM-dd HH:mm:ss.SSS z";

4. "yyyy-MM-dd HH:mm:ss.SSS";


Custom Events attributes

You can define the custom event attributes depending on your business needs. For example, in the event of adding a product to the cart, you can have the following attributes product name, product price, currency value, etc.



Limitations of custom events

  • You can only define custom events in the following datatypes
    • Boolean
    • Number 
    • String  (255 characters)
    • Date
  • The maximum limit to an event name is 100 characters
  • A custom event can have a maximum of 25 custom attributes for each data type.
  • The maximum length of an event name is 100 characters.
  • The maximum length of a String data type for an attribute is 255 characters.
  • The maximum length of an attribute name is 50 characters.
  • The name of your event or event attribute should not begin with fm_