# Events

For better insights into your customers, we evolved the events to use structured event data. This benefits you by improving results and giving a far more rich reporting dashboard.

Personal information

Sending us information about your customers helps us improve results - but unless approved by us please do not send any personally identifiable information. Truncate IP addresses and anonymize any data that could be used to identify an individual. Details in our privacy guide.

Tip

The event properties mentioned below can also be passed in the v query string parameter when using the Vision API endpoints.

E.g. /explore?v=user_id:7462402,page_type:pdp

# Common event properties

Property Type Description
anonymous_id String A unique identifier (UUID) for the current user (can be missing if user_id is specified)
user_id String The user identifier for logged in users. This must not be personally identifiable such as an email address.
user_ip String The truncated user IP (will be inferred automatically if missing but stored truncated).
Please remove the last octet / everything after the final .. E.g: 123.124.125.xxx
page_url String The current page URL (will be inferred automatically if missing)
page_referrer String This can be obtained from document.referrer (will be inferred from the Referer HTTP header if missing)
page_user_agent String It will be automatically inferred from the User-Agent HTTP header if missing

page_type

String

  • plp for a category listing page
  • pdp for a product details page
  • ve for a page meant for product exploration
  • other for other types of pages (default value)
timestamp Number The user timestamp (will default to the current timestamp)
ab_tests Object A/B tests the current user is included in
ab_tests.$.name String The A/B test name
ab_tests.$.group String The A/B test group for the current user
consent Number Whether this user has given consent for their data to be processed by Visii. More details in our privacy guide.

# Standard Events

# Page Loaded

Fire this event when an user loads a page, with or without Visii recommendations enabled on it.

// Example using Visii Analytics script - the event properties object is the "data" field for the track endpoint

// Example using all available properties
va.track("Page Loaded", {
	anonymous_id: "8c772995-b629-4051-a4e9-b7a30dbe5b32",
	user_id: "7462402",
	user_ip: "123.124.125.xxx",
	page_url: "https://www.my-website.com/products/my-awesome-product",
	page_referrer: "https://www.my-website.com",
	page_user_agent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_2) ...",
	page_type: "pdp",
	timestamp: 1577836800000,
	ab_tests: [
		{
			name: "visii-recommends",
			group: "visii"
		},
		{
			name: "homepage-cta",
			group: "control"
		}
	]
});

// Example with required properties
va.track("Page Loaded");

# Widget Loaded

Fire this event when the widget is loaded in the page.

// Example using all available properties
va.track("Widget Loaded", {
	anonymous_id: "8c772995-b629-4051-a4e9-b7a30dbe5b32",
	user_id: "7462402",
	user_ip: "123.124.125.xxx",
	page_url: "https://www.my-website.com/products/my-awesome-product",
	page_referrer: "https://www.my-website.com",
	page_user_agent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_2) ...",
	page_type: "pdp",
	timestamp: 1577836800000,
	ab_tests: [
		{
			name: "visii-recommends",
			group: "visii"
		},
		{
			name: "homepage-cta",
			group: "control"
		}
	]
});

// Example with required properties
va.track("Widget Loaded");

# Widget Viewed

Fire this event when the scrolled enough to see and interact with the widget.

// Example using all available properties
va.track("Widget Viewed", {
	anonymous_id: "8c772995-b629-4051-a4e9-b7a30dbe5b32",
	user_id: "7462402",
	user_ip: "123.124.125.xxx",
	page_url: "https://www.my-website.com/products/my-awesome-product",
	page_referrer: "https://www.my-website.com",
	page_user_agent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_2) ...",
	page_type: "pdp",
	timestamp: 1577836800000,
	ab_tests: [
		{
			name: "visii-recommends",
			group: "visii"
		},
		{
			name: "homepage-cta",
			group: "control"
		}
	]
});

// Example with required properties
va.track("Widget Viewed");

# Product Clicked

Fire this event when a product details page (PDP) link is clicked.

# Additional event properties

Property Type Description
product_id String The product ID used when using the Admin API (to push content) or Vision API (to get recommendations)
products_on_page Object Other products the user saw on the current page
products_on_page.$.id String The ID of the product the user saw but didn't click
// Example using all available properties
va.track("Product Clicked", {
	anonymous_id: "8c772995-b629-4051-a4e9-b7a30dbe5b32",
	user_id: "7462402",
	user_ip: "123.124.125.xxx",
	page_url: "https://www.my-website.com/products/735583523/my-awesome-product",
	page_referrer: "https://www.my-website.com",
	page_user_agent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_2) ...",
	page_type: "pdp",
	timestamp: 1577836800000,
	ab_tests: [
		{
			name: "visii-recommends",
			group: "visii"
		},
		{
			name: "homepage-cta",
			group: "control"
		}
	],
	product_id: "735583523",
	products_on_page: [
		{
			id: "245238456"
		},
		{
			id: "396734874"
		}
	]
});

// Example with required properties
va.track("Product Clicked", {
	product_id: "735583523"
});

# Product Searched

Fire this event when the user did a search by text action.

# Additional event properties

Property Type Description
search_string String The string the user used when searching
products_on_page Object Other products the user saw on the current page
products_on_page.$.id String The ID of the product the user saw but didn't click
// Example using all available properties
va.track("Product Searched", {
	anonymous_id: "8c772995-b629-4051-a4e9-b7a30dbe5b32",
	user_id: "7462402",
	user_ip: "123.124.125.xxx",
	page_url: "https://www.my-website.com/products/735583523/my-awesome-product",
	page_referrer: "https://www.my-website.com",
	page_user_agent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_2) ...",
	page_type: "pdp",
	timestamp: 1577836800000,
	ab_tests: [
		{
			name: "visii-recommends",
			group: "visii"
		},
		{
			name: "homepage-cta",
			group: "control"
		}
	],
  search_string: "elephants on the beach",
	products_on_page: [
		{
			id: "245238456"
		},
		{
			id: "396734874"
		}
	]
});

// Example with required properties
va.track("Product Searched", {
	search_string: "elephants on the beach"
});

# Product Displayed

Fire this event when the user visits a PDP page.

# Additional event properties

Property Type Description
product_id String The product ID used when using the Admin API (to push content) or Vision API (to get recommendations)
products_on_page Object Other products the user saw on the current page
products_on_page.$.id String The ID of the product the user saw but didn't click
// Example using all available properties
va.track("Product Displayed", {
	anonymous_id: "8c772995-b629-4051-a4e9-b7a30dbe5b32",
	user_id: "7462402",
	user_ip: "123.124.125.xxx",
	page_url: "https://www.my-website.com/products/735583523/my-awesome-product",
	page_referrer: "https://www.my-website.com",
	page_user_agent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_2) ...",
	page_type: "pdp",
	timestamp: 1577836800000,
	ab_tests: [
		{
			name: "visii-recommends",
			group: "visii"
		},
		{
			name: "homepage-cta",
			group: "control"
		}
	],
	product_id: "735583523",
	products_on_page: [
		{
			id: "245238456"
		},
		{
			id: "396734874"
		}
	]
});

// Example with required properties
va.track("Product Displayed", {
	product_id: "735583523"
});

# Product Favorited

Fire this event when the user adds a product the the favorite / wishlist.

# Additional event properties

Property Type Description
product_id String The product ID used when using the Admin API (to push content) or Vision API (to get recommendations)
// Example using all available properties
va.track("Product Favorited", {
	anonymous_id: "8c772995-b629-4051-a4e9-b7a30dbe5b32",
	user_id: "7462402",
	user_ip: "123.124.125.xxx",
	page_url: "https://www.my-website.com/products/735583523/my-awesome-product",
	page_referrer: "https://www.my-website.com",
	page_user_agent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_2) ...",
	page_type: "pdp",
	timestamp: 1577836800000,
	ab_tests: [
		{
			name: "visii-recommends",
			group: "visii"
		},
		{
			name: "homepage-cta",
			group: "control"
		}
	],
	product_id: "735583523"
});

// Example with required properties
va.track("Product Favorited", {
	product_id: "735583523"
});

# Order Completed

Fire this event when the user successfully completed an order.

# Additional event properties

Property Type Description
currency String The currency used in the order
tax String The tax amount
total_price Number The total order amount
order_id String The order identifier
shipping Number The shipping costs
items Object The items included in the order
items.$.price Number The product price
items.$.sku String The product ID
items.$.quantity Number The quantity for this product
// Example using all available properties
va.track("Order Completed", {
	anonymous_id: "8c772995-b629-4051-a4e9-b7a30dbe5b32",
	user_id: "7462402",
	user_ip: "123.124.125.xxx",
	page_url: "https://www.my-website.com/products/735583523/my-awesome-product",
	page_referrer: "https://www.my-website.com",
	page_user_agent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_2) ...",
	page_type: "pdp",
	timestamp: 1577836800000,
	ab_tests: [
		{
			name: "visii-recommends",
			group: "visii"
		},
		{
			name: "homepage-cta",
			group: "control"
		}
	],
	currency: "USD",
	tax: 10,
	total_price: 103,
	order_id: "oid293483",
	shipping: 5,
	items: [
		{
			price: 22,
			sku: "p29473",
			quantity: 1
		},
		{
			price: 33,
			sku: "p22473",
			quantity: 2
		}
	]
});

// Example with required properties
va.track("Order Completed", {
	currency: "USD",
	tax: 10,
	total_price: 103,
	order_id: "oid293483",
	shipping: 5,
	items: [
		{
			price: 22,
			sku: "p29473",
			quantity: 1
		},
		{
			price: 33,
			sku: "p22473",
			quantity: 2
		}
	]
});

# Custom Events

If you consider other events will be helpful to better understand the user behavior or you want that knowledge to be integrated into your client dashboard you can use custom events.

They follow the same format as standard events, having the same Common Event Properties. The data object can have additional fields related to your custom event.

// Example using Visii Analytics script - the event properties object is the "data" field for the track endpoint

// Example using all available properties
va.track("My custom event", {
	anonymous_id: "8c772995-b629-4051-a4e9-b7a30dbe5b32",
	user_id: "7462402",
	user_ip: "123.124.125.xxx",
	page_url: "https://www.my-website.com/products/my-awesome-product",
	page_referrer: "https://www.my-website.com",
	page_user_agent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_2) ...",
	page_type: "pdp",
	timestamp: 1577836800000,
	ab_tests: [
		{
			name: "visii-recommends",
			group: "visii"
		},
		{
			name: "homepage-cta",
			group: "control"
		}
	],
	customEventKey: customEventValue
});

// Example with required properties
va.track("My custom event", eventData);
Last Updated: 4/3/2020, 4:43:59 PM