Visii Documentation

# Events

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

If you are using Widgets supplied by Visii all their events are already tracked. You do need to add these events elsewhere on your site.

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 anonymise any data that could be used to identify an individual. Details in our privacy guide.

User tracking

We request that you send a GDPR compliant page_view_id value when requesting results from the Vision API.

Once a user consents, add the anonymous_id and user_id so these can be mapped to purchases.

Other event properties detailed 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,page_view_id:123456789

# Event Properties

# Common event properties

These events should be included on all track events sent to the API.

va.js

Consider using the Visii Analytics library, which populates many fields for you - making it easier to send the correct information to Visii to improve your results.

Property Type va.js Description
anonymous_id String A unique identifier (UUID) for the current user (can be missing if user_id is specified)
ab_tests Object A/B tests the current user is included in:
ab_tests.$.group String - The A/B test group for the current user
ab_tests.$.name String - The A/B test name
consent Number Whether this user has given consent for their data to be processed by Visii. More details in our privacy guide.
page_referrer String ✔ This can be obtained from document.referrer (will be inferred from the Referer HTTP header if missing)
page_type String - plp for a product listing page / category pages
- pdp for a product details page
- homepage for your homepage
- search for a plp generated by a user search (keyword or other)
- landing for a landing page
- visii-ve for a page meant for visual product exploration
- checkout for checkout and confirmation pages
- other for other types of pages (default value)
page_url String ✔ The current page URL (will be inferred automatically if missing)
page_user_agent String ✔ It will be automatically inferred from the User-Agent HTTP header if missing
page_view_id Number ✔ A privacy respecting unique identifier for each user visiting a page, which is included across all events originating from this page but expires per page - so not used for session tracking. It assists with caching of products_on_page and products_seen.
More details available in Visii Analytics library
products_on_page Object Products on the current page
products_on_page.$.id String The ID of a product on the page (the same id you use to identify content in a dataset
products_on_page.$.section String Which page section or widget contains a product, for example the carousel name the product is displayed in.
This can be any string that you find useful for identifying a section and must contain visii for our recommendations.
products_seen Object A subset of products_on_page that a user had in their viewport.
We recommend using our optimised va.js script to send these events as they occur. Alternatively send on other events (when a customer interacts or scrolls) rather than wait until the Product Clicked event to ensure they are all captured.
products_seen.$.id String The ID of the product the user has seen / product impression (the same id you use to identify content in a dataset.
products_seen.$.section String Which page section or widget contains a product, for example the carousel name the product is displayed in.
This can be any string that you find useful for identifying a section and must contain visii for our recommendations.
timestamp Number ✔ The user timestamp (will default to the current timestamp)
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

# Optional event properties

Specific to the event being sent, these properties are optional.

Property Type Description
product_id String The content/product ID used when using the Admin API (to push content) or Vision API (to get recommendations).
context_product_id String The optional content/product ID in context to an event. For example, a Product Clicked event within a Product Display Page, product_id is the product clicked, context_product_id is the Product Page product ID. A Product Listing Page would be an example where no context_product_id is required.
search_string String The string the user used when searching for text results.
section String Which page section or widget contains a product (must match those sent for products_on_page and products_seen), for example the carousel name the product is displayed in. This can be any string that you find useful for identifying a section and must contain visii for our recommendations.
list_name String The list a product has been added to:
* cart
* favorites
* custom-name
* other
[order data] * See the Order Completed event for a full list.

# Standard Events

# Page Loaded

Fire this event when a user lands on any 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
window.visii.track("Page Loaded", {
  anonymous_id: "8c772995-b629-4051-a4e9-b7a30dbe5b32",
  user_id: "7462402",
  page_type: "pdp",
  product_id: "232342",
  ab_tests: [
    {
      name: "visii-recommends",
      group: "visii"
    },
    {
      name: "homepage-cta",
      group: "control"
    }
  ],
  products_on_page: [
    {
      id: "245238456",
      section: "recently_viewed"
    },
    {
      id: "396734874",
      section: "recently_viewed"
    }
  ]
});

# Widget Loaded

Fire this event when a widget showing Visii results is loaded on the page or subsequent requests for data have loaded. Results returned should be sent in products_on_page.

// Example using all available properties
window.visii.track("Widget Loaded", {
  anonymous_id: "8c772995-b629-4051-a4e9-b7a30dbe5b32",
  user_id: "7462402",
  page_type: "pdp",
  ab_tests: [
    {
      name: "visii-recommends",
      group: "visii"
    },
    {
      name: "homepage-cta",
      group: "control"
    }
  ],
  products_on_page: [
    {
      id: "245238456",
      section: "visii_you_might_like"
    },
    {
      id: "396734874",
      section: "visii_you_might_like"
    },
    {
      id: "2452332423",
      section: "visii_you_might_like"
    },
    {
      id: "6893589",
      section: "visii_you_might_like"
    }
  ],
  products_seen: [
    {
      id: "245238456",
      section: "visii_you_might_like"
    },
    {
      id: "396734874",
      section: "visii_you_might_like"
    }
  ]
});

# Widget Viewed

Fire this event when the widget is in the viewport of the client browser. This is a good opportunity to send the products_seen in this widget.

Property Type Description
context_product_id String The optional product ID in context to an event. For example, a Product Clicked event a Product Page, product_id is the product clicked, context_product_id is the Product Page product ID. Usually the id being sent to the Vision API to generate results for this widget. Some scenarios, like on a Product Listing Page would not have a context_product_id.
// Example using all available properties
window.visii.track("Widget Viewed", {
  context_product_id: "4324255",
  anonymous_id: "8c772995-b629-4051-a4e9-b7a30dbe5b32",
  user_id: "7462402",
  page_type: "pdp",
  ab_tests: [
    {
      name: "visii-recommends",
      group: "visii"
    },
    {
      name: "homepage-cta",
      group: "control"
    }
  ],
  products_seen: [
    {
      id: "444238456",
      section: "you-might-like"
    },
    {
      id: "396734874",
      section: "you-might-like"
    }
  ]
});

# Product Clicked

Fire this event when a Product Details Page (PDP) link is clicked or a product is clicked inside an interactive widget. This is for all products, anywhere on your website, even those not recommended by Visii.

Property Type Description
product_id String The content/product ID used when using the Admin API (to push content) or Vision API (to get recommendations).
context_product_id String The optional product ID in context to an event. For example, a Product Clicked event a Product Page, product_id is the product clicked, context_product_id is the Product Page product ID. Usually the id being sent to the Vision API to generate results for this widget. Some scenarios, like on a Product Listing Page would not have a context_product_id.
section String Which page section or widget contains a product (must match those sent for products_on_page and products_seen), for example the carousel name the product is displayed in. This can be any string that you find useful for identifying a section and must contain visii for our recommendations.
// Example using all available properties
window.visii.track("Product Clicked", {
  context_product_id: "5554223",
  product_id: "735583523",
  anonymous_id: "8c772995-b629-4051-a4e9-b7a30dbe5b32",
  user_id: "7462402",
  page_type: "pdp",
  section: "visii_you_might_like",
  ab_tests: [
    {
      name: "visii-recommends",
      group: "visii"
    },
    {
      name: "homepage-cta",
      group: "control"
    }
  ],
  products_on_page: [
    {
      id: "245238456",
      section: "recently_viewed"
    },
    {
      id: "396734874",
      section: "recently_viewed"
    }
  ],
  products_seen: [
    {
      id: "245238456",
      section: "recently_viewed"
    }
  ]
});

# Product Searched

Fire this event when the user searches by text on your website. Ensure the list of products returned is tracked with the products_on_page property.

Property Type Description
search_string String The string the user used when searching
// Example using all available properties
window.visii.track("Product Searched", {
  search_string: "elephants on the beach",
  anonymous_id: "8c772995-b629-4051-a4e9-b7a30dbe5b32",
  user_id: "7462402",
  page_type: "plp",
  ab_tests: [
    {
      name: "visii-recommends",
      group: "visii"
    },
    {
      name: "homepage-cta",
      group: "control"
    }
  ],
  products_on_page: [
    {
      id: "245238456",
      section: "search_results"
    },
    {
      id: "396734874",
      section: "search_results"
    }
  ]
});

# Product Displayed

Fire this event when the user visits a Product Display Page (PDP).

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
window.visii.track("Product Displayed", {
  product_id: "735583523",
  anonymous_id: "8c772995-b629-4051-a4e9-b7a30dbe5b32",
  user_id: "7462402",
  page_type: "pdp",
  ab_tests: [
    {
      name: "visii-recommends",
      group: "visii"
    },
    {
      name: "homepage-cta",
      group: "control"
    }
  ],
  products_on_page: [
    {
      id: "245238456",
      section: "recently_viewed"
    },
    {
      id: "396734874",
      section: "recently_viewed"
    }
  ]
});

# Product Added

Fire this event when the user adds a product their shopping cart or favorites.

Property Type Description
product_id String The product ID used when using the Admin API (to push content) or Vision API (to get recommendations)
context_product_id String The optional product ID in context to an event. For example, a Product Clicked event a Product Page, product_id is the product clicked, context_product_id is the Product Page product ID. Usually the id being sent to the Vision API to generate results for this widget. Some scenarios, like on a Product Listing Page would not have a context_product_id.
list_name String The list a product has been added to:
* cart
* favorites
* custom-name
* other
// Example using all available properties
window.visii.track("Product Added", {
  product_id: "735583523",
  context_product_id: "53893",
  list_name: "cart",
  anonymous_id: "8c772995-b629-4051-a4e9-b7a30dbe5b32",
  user_id: "7462402",
  page_type: "pdp",
  ab_tests: [
    {
      name: "visii-recommends",
      group: "visii"
    },
    {
      name: "homepage-cta",
      group: "control"
    }
  ]
});

# Product Removed

Fire this event when the user removes a product their shopping cart or favorites.

Property Type Description
product_id String The product ID used when using the Admin API (to push content) or Vision API (to get recommendations)
context_product_id String The optional product ID in context to an event. For example, a Product Clicked event a Product Page, product_id is the product clicked, context_product_id is the Product Page product ID. Usually the id being sent to the Vision API to generate results for this widget. Some scenarios, like on a Product Listing Page would not have a context_product_id.
list_name String The list a product has been added to:
* cart
* favorites
* custom-name
* other
// Example using all available properties
window.visii.track("Product Removed", {
  product_id: "735583523",
  context_product_id: "53893",
  list_name: "cart",
  anonymous_id: "8c772995-b629-4051-a4e9-b7a30dbe5b32",
  user_id: "7462402",
  page_type: "pdp",
  ab_tests: [
    {
      name: "visii-recommends",
      group: "visii"
    },
    {
      name: "homepage-cta",
      group: "control"
    }
  ]
});

# Page Scrolled

Endpoint

We recommend using the va.js library to take care of all of these events.

Fire this event after the user scrolled the page or jumped to a different section in the page. To help you decide if the event is meaningful consider this:

  • Did the user jump to a section showing product recommendations? E.g. "Trending", "Recently Sold", "New Products", "Frequently bought together", "Customers who viewed this item also viewed"
  • Were the products generated by Visii? E.g visii-similar
  • Did the user see other products that weren't previously visible in the viewport?
  • Were new products added to the page? This could happen when infinite scrolling is supported or the user reached the end of page and you load new product suggestions.

If you plan to use this event to only report products_seen, we recommend using the Products Seen event.

Avoid spamming

Attention should be payed to avoiding sending the same information multiple times. Users can scroll up and down the page multiple times while deciding what they like. Once all products were seen there is no need to report scroll events for the current page.

Property Type Description
product_id String The product ID used when using the Admin API (to push content) or Vision API (to get recommendations) (Optional)
// Example using all available properties
window.visii.track("Page Scrolled", {
  product_id: "735583523",
  anonymous_id: "8c772995-b629-4051-a4e9-b7a30dbe5b32",
  user_id: "7462402",
  page_type: "pdp",
  ab_tests: [
    {
      name: "visii-recommends",
      group: "visii"
    },
    {
      name: "homepage-cta",
      group: "control"
    }
  ],
  products_on_page: [
    {
      id: "245238456",
      section: "trending"
    },
    {
      id: "396734874",
      section: "trending"
    },
    {
      id: "2452332423",
      section: "trending"
    },
    {
      id: "6893589",
      section: "trending"
    }
  ],
  products_seen: [
    {
      id: "245238456",
      section: "trending"
    },
    {
      id: "396734874",
      section: "trending"
    }
  ]
});

# Products Seen

Endpoint

We recommend using the va.js library to take care of all of these events.

Fire this event after the customer has seen a product.

If you plan to implement this yourself:

  • We recommend using a viewport intersection observer (opens new window) rather than scroll events for performance reasons
  • We recommend storing a cache of product IDs that have already been sent to reduce duplication/unnecessary requests
  • Ensure you pass in the page_view_id to connect events to a page view
  • Enable keepalive (opens new window) to ensure request is completed
  • Avoid spamming the same data, for performance and network reasons
Property Type Description
products_seen Object
products_seen.$.id String
products_seen.$.section String 
// Example using all available properties
window.visii.track("Products Seen", {
  anonymous_id: "8c772995-b629-4051-a4e9-b7a30dbe5b32",
  user_id: "7462402",
  page_type: "pdp",
  ab_tests: [
    {
      name: "visii-recommends",
      group: "visii"
    },
    {
      name: "homepage-cta",
      group: "control"
    }
  ],
  products_on_page: [
    {
      id: "245238456",
      section: "trending"
    },
    {
      id: "396734874",
      section: "trending"
    },
    {
      id: "2452332423",
      section: "trending"
    },
    {
      id: "6893589",
      section: "trending"
    }
  ],
  products_seen: [
    {
      id: "245238456",
      section: "trending"
    },
    {
      id: "396734874",
      section: "trending"
    }
  ]
});

# Order Completed

Fire this event when the user successfully completes an order.

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.$.id String The content ID (you use to identify content in a dataset).
items.$.price Number The product price
items.$.quantity Number The quantity for this product
items.$.* String A field to help identify variations. For example, size or sku, add these as items.$.size or items.$.sku (more details).
// Example using all available properties
window.visii.track("Order Completed", {
  anonymous_id: "8c772995-b629-4051-a4e9-b7a30dbe5b32",
  user_id: "7462402",
  page_type: "checkout",
  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: [
    {
      id: "994949",
      price: 22,
      quantity: 1,
      sku: "p29473-C",
      size: "child"
    },
    {
      id: "994949",
      price: 33,
      quantity: 2,
      sku: "p29473-A",
      size: "adult"
    }
  ]
});

# 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
window.visii.track("My custom event", {
  anonymous_id: "8c772995-b629-4051-a4e9-b7a30dbe5b32",
  user_id: "7462402",
  page_type: "pdp",
  page_view_id: 157783680000012345,
  timestamp: 1577836800000,
  ab_tests: [
    {
      name: "visii-recommends",
      group: "visii"
    },
    {
      name: "homepage-cta",
      group: "control"
    }
  ],
  customEventKey: customEventValue
});

// Example with required properties
window.visii.track("My custom event", eventData);
Last Updated: 6/30/2022, 12:24:16 PM

← Split Testing →