# 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

To connect these events together, use the anonymous_id and user_id when requesting results from the Vision API.

The event properties detailed below are passed in the v query string parameter when using the Vision API endpoints.

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

# 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 category listing page
  • pdp for a product details page
  • homepage for your homepage
  • landing for a landing page
  • 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 unique identifier for that user visiting the page view, which is included across all events originating from this page. Amongst other things it allows caching of products_on_page and products_seen.
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 The page section of the product, for example the carousel name the product is displayed in. This can be any string that you find useful for identifying.
products_seen Object A subset of products_on_page that a user had in their viewport. To ensure this is captured, we recommend sending as they interact, scroll rather than wait until the Product Clicked event.
products_seen.$.id String The ID of the product the user has seen (the same id you use to identify content in a dataset.
products_seen.$.section String The page section of the product, for example the carousel name the product is displayed in.
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 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.
search_string String The string the user used when searching for text results.

list_name

String

The list a product has been added to:

  • cart
  • favorites
  • custom-name
  • other
* * 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 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.
// 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 product ID in context to an event. For example, on Product Clicked on a Product Page, product_id is the product clicked, context_product_id is the Product Page product ID.
// 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",
  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_on_page: [
    {
      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 product ID in context to the event. For example, on a Product Page, the ID of that product.

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 product ID in context to the event. For example, on a Product Page, the ID of that product.

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"
    }
  ]
});

# 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: 8/4/2020, 1:24:32 PM