User Events

Getting Started

USER EVENTS:

User events in a Customer Data Platform (CDP) refer to the actions and behaviors that users take across different digital channels, like website visits, clicks, or purchases. These events are tracked and recorded with details such as timestamps, attributes (like product details), and are used to create a complete picture of user engagement. You can use these api endpoints to create and view user activity.

Must to know : Include your Auth key in the request headers. Register to MSG91 and get you Auth token.

Create User Events:

The user events will be created using the below format,Use these Create User Events API to send data.

Payload:

Key	Format	Requirement	Description
data.*	array	Required	Array of the different events
data.*.event_name	string	Required	Name of the event
data.*.visitor_id	string	Required	Contact_id of the user
data.*.event_properties	json	Required	Meta data of the event
data.*.event_timestamp	string	Optional	Timestamp: YYYY-MM-DD HH:MM:SS
data.*.context	json	Optional	System attributes of user
data.*.type	string	Optional	Parent Type for event, default value:track
data.*.created_at	string	Implicit	The timestamp when the event was stored on segmento.

Note: The events will categorized as failed if general validations are failed or visitor_id not exists in respective phonebook

We classify user events based on their Event Types in 2 ways:

Custom Events - Events that we receive from you apart from the default events types. To register the products via custom event send the product details in product key. These can be either array or the single product, The product must register on the behalf of product_id .

Default Events - Events that are pre-registered on segmento and are validated. When you send the events for below event names it will be validated according to defined format.

product-clicked :When a user clicks any product these get captured and contain single product details.

Key	Format	Requirement	Description
sku	string	Optional	Sku of the product being viewed
category	string	Optional	Product category being viewed
name	string	Optional	Name of the product being viewed
product_id	string	Required	id of the product being viewed
brand	string	Optional	Brand associated with the product
variant	string	Optional	Variant of the product
variant_id	string	Optional	Id for the variant
price	string	Optional	Price of the product being viewed
quantity	string	Optional	Quantity of a product
coupon	string	Optional	Coupon code associated with a product
position	string	Optional	Position in the product list
url	string	Optional	URL of the product page
image_url	string	Optional	Image url of the product

product-searched: When a user searches the product , these may generally be done at the product search bar.

Key	Format	Requirement	Description
query	string	Required	Query that user searched for

remove-from-cart

When the user removes the product from the cart it gets captured ,use this event type and send the details of the product in the specified payload.

Key	Format	Requirement	Description
checkout_id	string	Required	Query that user searched for
order_id	string	Optional	Order id for the that order
shipping_method	string	Optional	Method of shipping
payment_method	string	Optional	Method of the payment

add-to-cart:

When the user adds a product in cart, use this event type and send the details of product in the specified payload.

Key	Format	Requirement	Description
cart_id	string	Required	Id of the cart
product_id	string	Required	id of the product being viewed
sku	string	Optional	Sku of the product being viewed
category	string	Optional	Product category being viewed
name	string	Optional	Name of the product being viewed
brand	string	Optional	Brand associated with the product
variant	string	Optional	Variant of the product
variant_id	string	Optional	Id for the variant
price	string	Optional	Price of the product being viewed
quantity	string	Optional	Quantity of a product
coupon	string	Optional	Coupon code associated with a product
position	string	Optional	Position in the product list
url	string	Optional	URL of the product page
image_url	string	Optional	Image url of the product

payment-info:

Capture this event whenever a user successfully enters payment information. This event happens generally before the product purchase.Contains payment method , shipment method and other details.

Key	Format	Requirement	Description
checkout_id	string	Optional	Query that user searched for
order_id	string	Optional	Order id for the that order
shipping_method	string	Optional	Method of shipping
payment_method	string	Optional	Method of the payment

product-added-to-wishlist:

When the user adds a product to the wishlist these events get captured.

Key	Format	Requirement	Description
wishlist_id	string	Optional	Id of the cart
wishlist_name	string	Optional	Name of wishlist
product_id	string	Optional	id of the product being viewed
sku	string	Optional	Sku of the product being viewed
category	string	Optional	Product category being viewed
name	string	Optional	Name of the product being viewed
brand	string	Optional	Brand associated with the product
variant	string	Optional	Variant of the product
variant_id	string	Optional	Id for the variant
price	string	Optional	Price of the product being viewed
quantity	string	Optional	Quantity of a product
coupon	string	Optional	Coupon code associated with a product
position	string	Optional	Position in the product list
url	string	Optional	URL of the product page
image_url	string	Optional	Image url of the product

product-viewed:

When the user views a product , on your website, it contains the product detail of a single product.

Key	Format	Requirement	Description
product_id	string	Required	id of the product being viewed
sku	string	Optional	Sku of the product being viewed
category	string	Optional	Product category being viewed
name	string	Optional	Name of the product being viewed
brand	string	Optional	Brand associated with the product
variant	string	Optional	Variant of the product
variant_id	string	Optional	Id for the variant
price	string	Optional	Price of the product being viewed
quantity	string	Optional	Quantity of a product
coupon	string	Optional	Coupon code associated with a product
position	string	Optional	Position in the product list
url	string	Optional	URL of the product page
image_url	string	Optional	Image url of the product

product-reviewed

When the user reviews a product , on your website, review_id and rating are required for this event type.

Key	Format	Requirement	Description
product_id	string	Required	Id of product being reviewed
review_id	string	Required	Review id
review_body	string	Optional	Review
rating	string	Optional	rating

product-list-viewed

When the user sees a list of products on your website, we receive an event with all the product details on the list.

Key	Format	Requirement	Description
list_id	string	Optional	List id of the product
category	string	Optional	Category of list
products.*	array	Required	List of the product
products.*.product_id	string	Required	Id of product being reviewed
products.*.sku	string	Optional	Sku of the product being viewed
products.*.category	string	Optional	Product category being viewed
products.*.name	string	Optional	Name of the product being viewed
products.*.brand	string	Optional	Brand associated with the product
products.*.variant_id	string	Optional	Id for the variant
products.*.price	string	Optional	Price of the product being viewed
products.*.quantity	string	Optional	Quantity of a product
products.*.coupon	string	Optional	Coupon associated with product
products.*.position	string	Optional	Position in the product list
products.*.url	string	Optional	URL of the product page
products.*.image_url	string	Optional	Image url of the product

order-updated:

When a user update their order on your website we receive this event with order_id and all the details in that order.

Key	Format	Requirement	Description
order_id	string	Optional	Id of the order
affiliation	string	Optional	Affiliation for the order
total	numeric	Required	Total of the order
revenue	numeric	Optional	Total revenue
shipping	numeric	Optional	Shipping cost
tax	numeric	Optional	Tax
coupon	string	Optional	Coupon code
currency	String	Optional	Currency type
products.*	array	Optional	List of the product
products.*.sku	string	Optional	Sku of the product being viewed
products.*.product_id	string	Required	Id of product being reviewed
products.*.category	string	Optional	Product category being viewed
products.*.name	string	Optional	Name of the product being viewed
products.*.brand	string	Optional	Brand associated with the product
products.*.variant	string	Optional	Variant of the product
products.*.variant_id	string	Optional	Id for the variant
products.*.price	string	Optional	Price of the product being viewed
products.*.quantity	string	Optional	Quantity of a product
products.*.coupon	string	Optional	Coupon associated with a product
products.*.position	string	Optional	Position in the product list
products.*.url	string	Optional	URL of the product page
products.*.image_url	string	Optional	Image url of the product

order-completed

When the user completed the order and an order/transaction was successfully completed by the customer.These may contain multiple product details that were in the cart.

Key	Format	Requirement	Description
order_id	string	Optional	Id of the order
checkout_id	string	Optional	Checkout id for the order
total	numeric	Optional	Total of the order
revenue	numeric	Optional	Total revenue
shipping	numeric	Optional	Shipping cost
discount	numeric	Optional	Amount discounted
tax	numeric	Optional	Tax
coupon	string	Optional	Coupon code
currency	String	Optional	Currency type
products.*	array	Required	List of the product
products.*.product_id	string	Required	Id of product being reviewed
products.*.sku	string	Optional	Sku of the product being viewed
products.*.category	string	Optional	Product category being viewed
products.*.name	string	Optional	Name of the product being viewed
products.*.brand	string	Optional	Brand associated with the product
products.*.variant	string	Optional	Variant of the product
products.*.variant_id	string	Optional	Id for the variant
products.*.price	string	Optional	Price of the product being viewed
products.*.quantity	string	Optional	Quantity of a product
products.*.coupon	string	Optional	Coupon code associated with a product
products.*.position	string	Optional	Position in the product list
products.*.url	string	Optional	URL of the product page
products.*.image_url	string	Optional	Image url of the product

order-cancelled

Use this event type to specify that the order has been canceled by the user. Fire this when order is cancelled in process.

Key	Format	Requirement	Description
order_id	string	Optional	Id of the order
total	numeric	Optional	Total of the order
coupon	string	Optional	Coupon code
currency	String	Optional	Currency type
products.*	array	Required	List of the product
products.*.product_id	string	Required	Id of product being reviewed
products.*.sku	string	Optional	Sku of the product being viewed
products.*.category	string	Optional	Product category being viewed
products.*.name	string	Optional	Name of the product being viewed
products.*.brand	string	Optional	Brand associated with the product
products.*.variant	string	Optional	Variant of the product
products.*.variant_id	string	Optional	Id for the variant
products.*.price	string	Optional	Price of the product being viewed
products.*.quantity	string	Optional	Quantity of a product
products.*.coupon	string	Optional	Coupon associated with a product
products.*.position	string	Optional	Position in the product list
products.*.url	string	Optional	URL of the product page
products.*.image_url	string	Optional	Image url of the product

order-refunded

Use this event type to notify that the order has been refunded after delivery.

Key	Format	Requirement	Description
order_id	string	Optional	Id of the order
total	numeric	Optional	Total of the order
coupon	string	Optional	Coupon code
currency	String	Optional	Currency type
products.*	array	Required	List of the product
products.*.product_id	string	Required	Id of product being reviewed
products.*.sku	string	Optional	Sku of the product being viewed
products.*.category	string	Optional	Product category being viewed
products.*.name	string	Optional	Name of the product being viewed
products.*.brand	string	Optional	Brand associated with the product
products.*.variant	string	Optional	Variant of the product
products.*.variant_id	string	Optional	Id for the variant
products.*.price	string	Optional	Price of the product being viewed
products.*.quantity	string	Optional	Quantity of a product
products.*.coupon	string	Optional	Coupon associated with a product
products.*.position	string	Optional	Position in the product list
products.*.url	string	Optional	URL of the product page
products.*.image_url	string	Optional	Image url of the product

page-view

When the user goes to or is redirected to any page we need a page view event that contains the title of the page viewed by the user on your website.

Key	Format	Requirement	Description
title	string	Required	Id of product being reviewed
url	string	Optional	Review id
name	string	Optional	Review
channel	string	Optional	rating
meta	array	Optional	Other data to be send

Note: The variants will be registered only if the variant (its name) and variant_id/sku are sent.We will consider sku as the variant_id if it is not set.

What Segmento does Intelligently?

When we receive Default Events which have product_id in them, and the product is not already present in your product_catalog(explained later) we add the new product to it.

If we receive the default events whose keys are in invalid formats we put them in failed events, along with the reason why they were failed.

For custom events you create products by sending the product details in the product key.Make sure to send the product_id along with product details , otherwise products will not be saved.

Get Users Based On persona: This is the API you can use to ask a query in English like “Give me all users who have performed an add-to-cart event where the product is red shirt” and you get the list of all users who match that persona.

You can access the url for getting users based on persona by clicking Users Based On Persona

PRODUCT CATALOG:

A product catalog is an organized collection of all products that a store offers. It serves as a central repository where detailed information about each product, including name, description, price, and stock availability, is stored. This catalog is essential for managing the inventory of an e-commerce store and plays a crucial role in understanding your listed products.

We dynamically create the product catalog of your Phonebook, from the User events performed on your store.

Get Product Catalog - This is the API that you can use to get a product catalog for a particular phonebook.

You can access the url for getting product catalog by clicking Get Product Catalog.

EVENT TYPES:

The event Type api will let you know what are the different event Types are recorded on your CDP associated phonebook.
and also you can get what are the keys recorded for it.GET EVENT TYPE

Note: The keys in the event properties will be recorded up to two levels of JSON nesting, but the event data itself can be further nested.

FAILED USER EVENTS:

A user event is classified as failed when it fails our validation, e.g. when none of visitor_id is not present in the phonebook or product_id is passed as array other than string.Get FAILED EVENTS

This categorization serves a valuable purpose by helping users identify events that require attention. By viewing the failed events, users can access an error column that provides specific details on why an event failed validation.

This enables users to pinpoint and rectify any issues in their user events, ensuring that their data is accurate and aligns with the required format and criteria. This proactive approach not only streamlines data quality but also facilitates smoother data analysis and insights.