Event Tracking
At a broad level, AristanderAI does two things: it ingests user events (order placements, item view, account registrations, etc.) and it recommends prices.
We need to track all user behavior throughout the site and send this data to an external API. This includes page views, basket changes, order placements, and logins.
We need to be able to change prices of items within the site - the prices will be provided via an external API. If possible, we prefer to push prices - this needs to be discussed - otherwise, prices must be fetched every hour.
The onboarding process will take place in 4 steps:
1) Manual integration of event tracking on your e-commerce site (logins, page views, orders, etc.)
2) Integrating our pricing API (this endpoint will provide the prices)
3) Configuring your pricing settings
4) Customization of your pricing dashboard
Below, we cover each of the steps in detail.
For production use, the following base endpoint should be used: https://api.aristander.ai
Each request to the AristanderAI API will require an API key. This key will be provided to your team upon registration. During the initial testing + setup phase, a demo key will be provided.
Every session must be able to be uniquely identified. For the majority of requests listed below, a session_id parameter is supplied. This parameter MUST be unique to the session, and should consist of only ASCII alphanumeric characters.
There are several events that must be tracked throughout the user session. At the end of the tracking of an example session, we might have a sequence of events that look like this:
[[ “event_type” : “page”, “page_name” : “homepage”, “products” : [ … ]],[ “event_type” : “page”, “page_name” : “product_page”, “products” : [ … ]],[ “event_type” : “basket”, “action” : “addition”, “products” : [ … ]],[ “event_type” : “login”, “user_id” : “4” ],[ “event_type” : “order”, “order_information” : [ … ]],]
In the above case, a user navigated to the homepage, then to a product page, then added a product, and finally they logged in and placed an order.
Each event contains some common parameters:
api_version - this should be set to '1.1'
plugin_version - set this to "CompanyName-PluginVersion"
user_agent - a string representing the user's browser user agent string
timestamp - a UNIX timestamp at the moment of event creation in milliseconds
pricelist_source - this indicates the source of the current pricelist - if the prices for the event came from Aristander, this should be set to 'aristander'. If the prices for the event came from any other source, it should be set to 'original'. If relying upon AristanderAI for A/B testing, this will be provided via the /prices API. See the prices API for more details.
price_mode - this should be set to the mode of A/B testing you are using:
Set to 'split' if you are performing your own A/B testing and splitting the pricelists based on sessions
Set to 'timeseries' if you are either using AristanderAI to perform A/B testing - or you are showing one pricelist at a time (for example, switching the pricelist every hour)
Set to 'fixed' if at any point in time you switch to using one pricelist only - without any A/B testing
model_params - this is a string that will come from the /prices API. See the prices API for more details.
Every page visit must trigger a page event.
A page events encoded as JSON looks like the following:
{"event_type" : "page","session_id" : "098f6bcd4621d373cade4e832627b4f6","event_details" : {"products" : [{"product_id" : "6","price" : "5.9","currency_code" : "USD"},{"product_id" : "10","price" : "8.9","currency_code" : "USD"}],"page_name" : "home","page_url" : "http://magento2.test"},"api_version" : "1.1","plugin_version" : "CompanyName-PluginVersion","user_agent" : "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36","pricelist_source" : "aristander","price_mode" : "split","model_params" : "56720967f573f276008b2e0c6844bbbd","timestamp" : 1565252389074}
products - objects containing a product_id, the price, and the currency code (ISO 4217). Each element in the list should correspond to a product being displayed to the user.
page_name - a colloquial page name
page_url - the full URL of the page
There are a few required page types: homepage, basket, product_page, checkout, search.
It is vitally important that the page call tracks all of the products/prices shown to each user. If the page type is product_page, then the first product in the list should represent the product being visited.
Every basket modification must trigger a basket event. This includes additions/deletions/quantity modifications.
The basket details contain a few parameters: "action", "amount", and "product_ids".
The "action" parameter specifies the action that the user performed. If the user added an item, this parameter is set to "addition", if the user deleted an item this parameter is set to "deletion", if the user increased a quantity the parameter is set to "increase_quantity", and if the user decreased a quantity this parameter is set to "decrease_quantity".
The "product_id" parameter is the product affected by the basket modification.
The "price" parameter should refer to the price of the item affected.
The "quantity" parameter refers to the number of items affected, e.g. if two items are added or deleted, this should be "2".
Every action must be an additional call to the API.
{"event_type" : "basket","session_id" : "098f6bcd4621d373cade4e832627b4f6","event_details" : {"action" : "addition","product_id" : "106","price" : "10.60","quantity" : "1","currency_code" : "USD"},"api_version" : "1.1","plugin_version" : "CompanyName-PluginVersion","user_agent" : "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36","pricelist_source" : "aristander","price_mode" : "split","model_params" : "56720967f573f276008b2e0c6844bbbd","timestamp" : 1565252389074}
This event associates a user ID with a session ID - as soon as the user is known to be associated with the session, this event should be recorded.
{"event_type" : "login","session_id" : "098f6bcd4621d373cade4e832627b4f6","event_details" : {"user_id" : "4092"},"api_version" : "1.1","plugin_version" : "CompanyName-PluginVersion","user_agent" : "Firefox","pricelist_source" : "aristander","price_mode" : "split","model_params" : "56720967f573f276008b2e0c6844bbbd","timestamp" : 1565252389074},
An order event is created upon order submission (i.e., after a user places an order).
The order event has several parameters:
products - this should be a list of objects representing each product in the basket, each item has a product ID, a quantity, and an item price
order_costs - any associated order costs, as a list of lists - the first item should be the name of the cost, and the second should be the associated cost.
total - the total amount of the order displayed to the user
total_taxes - this should be included in your total_costs (below) - but is a separate line item denoting how much tax was charged to the user
total_costs - this should be the total amount of costs to place the order - it should be the sum of the net unit costs for all items and any order-level costs (taxes, etc.) - if we subtract this number from the "total", we should arrive at the order profit - see order costs for more details
currency_code - this represents the currency used for this order
{"event_type" : "order","session_id" : "098f6bcd4621d373cade4e832627b4f6","event_details" : {"products" : [{"product_id" : "106","quantity" : "2","item_price" : "1.06",}],"order_costs" : [["shipping", "5.00"]],"total" : "30.60","total_taxes" : "5.00","total_costs" : "10.40","currency_code" : "USD"},"api_version" : "1.1","plugin_version" : "CompanyName-PluginVersion","user_agent" : "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36","pricelist_source" : "aristander","price_mode" : "timeseries","model_params" : "56720967f573f276008b2e0c6844bbbd","timestamp" : 1565252389074}
This event is used to signify the creation of a new user. It has a single parameter: user_id - which should be the uniquely identifiable ID assigned to this user.
{"event_type" : "user_creation","session_id" : "098f6bcd4621d373cade4e832627b4f6","event_details" : {"user_id" : "4092"},"api_version" : "1.1","plugin_version" : "CompanyName-PluginVersion","user_agent" : "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36","pricelist_source" : "aristander","price_mode" : "split","model_params" : "56720967f573f276008b2e0c6844bbbd","timestamp" : 1565252389074}
This event should be sent on an interval, roughly every hour. It is solely used to make sure that the events are being submitted properly.
{"event_type" : "ping","api_version" : "1.1","plugin_version" : "CompanyName-PluginVersion","event_details" : {},"timestamp" : 1565252389074}
Events are submitted over HTTPS via POST, encoded as JSON. Event should be batched to reduce the number of calls to our server.
All events should be wrapped in a root level "events" list.
An example curl call demonstrating this:
curl --header "Content-Type: application/json"-d '{"events" : [{"event_type" : "ping","event_details" : {},"plugin_version" : "CompanyName-PluginVersion","api_version" : "1.1","timestamp" : 1565252389074}]}'-u demo: https://api.aristander.ai/events
And the accompanying JSON:
{ "events" :[{"event_type" : "ping","event_details" : {},"plugin_version" : "CompanyName-PluginVersion","api_version" : "1.1","timestamp" : 1565252389074}]}
For errors, please see the error page.