Events are referred to as any action performed by your users on your web app/website such as adding the product to cart, purchase of a product, adding the product to a wishlist, submitting a form, clicking a button, email click, email open, etc. Whenever an event occurs an attribute will be attached to these events, which contain information of when and where these events happened eg: from which device this event happened, from which operating system it happened, at what time it happened, from which location and timezone it happened etc

 

This event-related information can be used by you to understand your visitors & users better and also it can be used to segment your users based on their actions and run specific personalized campaigns or automated drip campaigns for them.

 

We recommend you to continue the process of integrating the events on your webpage/web app only if you are familiar with the usage of events and attributes in all main platforms such as Java, JS, Android & IOS, Webapps. If not, please seek your developer's help for the same. 

 

We recommend you to take a note of down all events you would like to track along with their attributes & Data types.


Note: Data types once defined cannot be changed later, so we request you to be sure of what data type you are defining before starting. Your web application will not be able to record data if the datatype received is different than what was defined in the beginning.


 

Before we go ahead with the events on the web application, please refer to the below table to know our base attributes. 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

 

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_timestamp

datetime

Event occurred time



Your web application supports two types of marketing events: system events & custom events


System Events


System events will be captured automatically, in addition to all the events performed by the user in the Journey workflow, Bulk campaigns also will be captured. To learn more about system events, refer this article.



Custom Events


Custom events are the events that are sent by you to the web application, these events are user-defined. This can be any action performed by your users on your website/web apps such as Added to wishlist, Added to cart, Product ordered, Product purchased, Payment failed, etc, you can define these events based on your needs.



Associate Visitor API

Frontend API: 


FM.associateVisitor("johny.depp@hollywood.com");


In the above screenshot, ‘johnny.depp’ is an ANONYMOUS user who visited the 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 web application.

Rest API:

curl -XPOST -H "fm-token:jrr3g04b0atvta4tmghbguhgugvd03r9n8v7eon7mv1b7qa" 'http://<domain>.freshworkscrm.com/crm/marketer/mas/api/v1/contacts/associate-visitor' -d '{"visitor_id": "1564408766806r0.8685208684454182", "email": "johnny.depp@hollywood.com"}'

Note: If contact is not present in your web application, the above API will create a new contact



Custom Event API


Frontend API


FM.trackCustomEvent("Added to cart",

{

"email": "david.thompson@sample.com",

"price": 100.21,

"currency": "USD",

"is_mobile_transaction": true,

"return date": "2019-12-30"

});



Rest API

curl --XPOST 'https://d2c-demo-1.myfreshworks.com/crm/marketer/mas/api/v1/events?email=david@abc.com&event_name=Custom_Signup&event_timestamp=2023-11-24T20:00:00Z' \

--header 'Content-Type: application/json' \

--data '{

 "price":1000,

"currency":"USD"

}'


Here, the event_timestamp parameter is required only if the event occurred in the past. If the timestamp is not present, the current time will be taken as the timestamp.


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";



Use Non-email as an identifier


Custom events by default take email as the identifier. But if you want to use any other field (for eg: mobile number’) as the identifier, you can use ‘identifier_name’ and ‘identifier_value’ parameters.




curl --XPOST 'https://domain.myfreshworks.com/crm/marketer/mas/api/v1/events?identifier_name=cf_client_id&identifier_value=123456&event_name=Stocks_purchased' --header 'Content-Type: application/json' 

--data  '{

 "Event Name" : "Stock_Purchase",

  "Event Date" : "10/07/2023",

  "Stock Name" : "testing",

  "Place" : "USA"

}'


Custom Event Attributes


Custom event attributes are user-defined, you can define custom event attributes depending on your requirement and your business needs.


For eg: Product added to the cart, can have the following attributes product name, product price, currency value, etc.


Limitations of Custom Event:


Your web application supports the following Datatypes:

  1. Boolean

  2. Number

  3. String  (255 characters)

  4. Date 


  • Event name can be max (100 characters)

  • A custom event can have a maximum of 25 custom attributes per data type( Boolean, Number, String, Date (i.e. 25 custom attributes of Number data type, 25 custom attributes of String data type, etc.).

  • 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_