Event REST API ¶
Here you will find description of Event REST API, which is used by Luigi’s Box collector to send information about user interaction with site search features. It might be used by other clients in environments, where Luigi’s Box javascript collector is not available (e.g., mobile application).
The API can receive following types of events:
- pageview (“pv”) - which can hold information about any product lists shown to the user
- click - which is used to capture interaction with the site, mainly with products lists
- event - an event, which is analogous to
pageview
, but triggered without an actual page reload - mainly if you need to report a new list, which appeared asynchronously.
All events are expected to be HTTP POST-ed to https://api.luigisbox.com
.
Pageview event ¶
Pageview event is a a basic event which tracks a pageview done by the user.
Pageview event example
{
"type": "pv",
"tracker_id": "1234-56678",
"client_id": 6969470340316755000,
"customer_id": 4739473924329473000,
"local_timestamp": 1626386701,
"app_version": "fe136c8",
"id": 6985277691922445000,
"url": "https://www.eshop.com/",
"path": "/",
"title": "Demo shop page title",
"referer": "",
"context": {
"warehouses": ["London", "Prague"],
"is_business": 1
},
"consent_granted": true,
"from_list_id": "1abc2de3-f456-7890-1g23-hijk45l6789m"
}
You should send a pageview event for any pageview done by the user, regardless of the page type - i.e., send the pageview for title page, product detail, category listing, blog post, etc.
The pageview event defines the basic event structure that you'll be using for all other event types:
attribute | explanation |
---|---|
type REQUIRED |
Can have values pv (pageview), click or event . The event type can used for cases when you, e.g., need to report a new list, which appeared asynchronously, without page reload (e.g., when continuous scrolling is implemented) and as such, it is not appropriate to report a pageview. |
tracker_id REQUIRED |
The site tracker_id from Luigi's Box Analytics. |
client_id REQUIRED |
An identifier of the user, preferably numeric. Make sure that it is unique for each distinct user. |
customer_id optional |
An identifier of the logged in user (in your system). Make sure that it is unique for each registered user. |
local_timestamp optional |
Local timestamp in seconds. |
app_version optional |
Version string of your integration. |
id REQUIRED |
Globally unique ID of the event. |
url recommended |
If the page/view is related to one particular product (e.g., product detail page) use product identifier here (the same you are using as identity in product catalog being synced to Luigi's Box). Otherwise send URL if there is one. |
path optional |
Path part of the URL. |
title optional |
Title of the page. |
referer optional |
Referer URL. |
context optional |
Context of the session / user (e.g. used warehouse within session). Should hold the key-value pairs consistent with what is pushed into the catalog data. |
consent_granted optional |
Set true , if a user has granted consent for personalization. |
from_list_id optional |
Identifier of the list from which the user was redirected to your site (e.g. identifier of the newsletter recommendation list). |
List event ¶
You should report every list of products shown to the user to our event API. Here, you can see an example of an event, which includes a "Search Results" list of products. Please, also pay attention to section "Pageview event" that describes pageview events in general.
List event example
{
"type": "event",
"lists": {
"Search Results": {
"items": [
{
"title": "a product",
"type": "item",
"url": "https://www.eshop.com/a-product",
"position": 1,
"price": 19
},
{
"title": "Another product",
"type": "item",
"url": "https://www.eshop.com/another-product",
"position": 2,
"price": null
},
{
"title": "Different product",
"type": "item",
"url": "https://www.eshop.com/different-product",
"position": 3,
"price": 351.36
},
{
"title": "Last product",
"type": "item",
"url": "https://www.eshop.com/last-product",
"position": 4,
"price": 853.71
}
],
"query": {
"string": "product",
"filters": {
"brand": "a brand scope",
"sort by": "price_amount:asc",
"_version": "8.0.6"
}
}
}
},
"tracker_id": "1234-5678",
"client_id": 6667519810961010000,
"local_timestamp": 1598019019,
"id": 6667520098487994000,
"url": "https://www.eshop.com/search",
"path": "/search",
"title": "Demo shop page title"
}
Every event must have a unique identifier ("id") and every event must be assigned to a user, identified by "client_id".
You can use static values in contexts, where "url" and "path" do not make sense (e.g., mobile application).
List event contains a hash of lists (under the required attribute lists
). Here, each list is represented as a key-value hash, where the key is the name of the list (e.g., "Search Results", "Autocomplete" and "Recommendation") and value is a definition of a list:
attribute | explanation |
---|---|
items REQUIRED |
List of items in the list. |
query REQUIRED |
Query definition for the list. Contains query string and filters. |
Items ¶
Every list in List event contains a list of the items (under attribute "items") with the following attributes:
attribute | explanation |
---|---|
title REQUIRED |
Title of the item. |
type REQUIRED |
Type of the item (e.g., "item", "product", "brand", "category"). This is used to distinguish different sub-lists within a list, for instance when autocomplete shows products, brands, categories etc. |
url REQUIRED |
Identifier of the item, generally url. |
position REQUIRED |
Position of the item in a list. |
price optional |
Price of the item. |
Query ¶
The "query" part of the list consists of "string" and "filters". Both parts are optional, but at least one of them must be present. By leaving out the "string" part, you can collect events related to navigation through hierarchy of categories on your site.
If you are using pagination, then you must send a pv event for every subsequent pagination view. Positions of the items should be relative to the first page, e.g., if a use clicks on page 2 and you have 20 items per page, the first item position should be 21. If you are using infinite-scroll style pagination, make sure that you are only sending the list items that were appended to the infinite list and NOT all items from the beginning.
Recommendation list event ¶
You should report every list of recommended products shown to the user to our event API. Please, also pay attention to section "List event" that describes list events in general.
Here, you can see an example of an event, which includes a "Recommendation" list of products.
Recommendation list event example
{
"type": "event",
"lists": {
"Recommendation": {
"items": [
{
"title": "a product",
"type": "item",
"url": "https://www.eshop.com/a-product",
"position": 1,
"price": 19
},
{
"title": "Another product",
"type": "item",
"url": "https://www.eshop.com/another-product",
"position": 2,
"price": null
},
{
"title": "Different product",
"type": "item",
"url": "https://www.eshop.com/different-product",
"position": 3,
"price": 351.36
},
{
"title": "Last product",
"type": "item",
"url": "https://www.eshop.com/last-product",
"position": 4,
"price": 853.71
}
],
"query": {
"filters": {
"ItemIds": ["/some-product"],
"RecommendationId": "1abc2de3-f456-7890-1g23-hijk45l6789m",
"Recommender": "meta_recommender",
"RecommenderClientId": "replacements_item_detail",
"Type": "complementary_combined_assoc",
"_Variant": "Luigis"
}
}
}
},
"tracker_id": "1234-5678",
"client_id": 6667519810961010000,
"local_timestamp": 1598019019,
"id": 6667520098487994000,
"url": "https://www.eshop.com/search",
"path": "/search",
"title": "Demo shop page title"
}
Each recommendation list event must contain query filters with the following key-value pairs. Values for the keys can be found in the recommendation request or recommendation request result.
key | explanation |
---|---|
RecommenderClientId REQUIRED |
Unique identifier of the recommender (recommender_client_identifier from recommendation result). Its value should define type of recommender user along with its position on the site (e.g., product_detail_bottom_alternatives ). |
RecommendationId REQUIRED |
Unique identifier of a set of recommended items (recommendation_id from recommendation result). Required for new integrations of Luigi's Box Recommender. We strongly recommend to update existing integrations as well. |
ItemIds optional |
List of input items of a recommendation request (item_ids from recommendation request). |
Recommender optional |
Name of the recommender (recommender from recommendation result). |
Type optional |
Type of the recommender (recommendation_type from recommendation result). |
_Variant optional |
Determines variant in A/B testing (e.g., Original, Luigis). |
How to set RecommenderClientId ¶
RecommenderClientId usually consists of three parts:
- location of the recommender (e.g.,
item_detail
,basket
,basket_popup
,homepage
,news
), - recommendation type (same as
recommendation_type
, e.g.personalized
, optional), - A/B test variant (
original
/luigis
, when not requesting Luigis' Box Recommender, always useoriginal
).
These three parts must always be lowercased and joined by a symbol _
. Please, avoid using any other characters than a-z and _
.
Several examples of Recommender Client Identifiers:
- in item's detail:
item_detail_complement_original
,item_detail_original
,item_detail_personalized_original
, - basket:
basket_popup_original
,basket_original
, - homepage:
homepage_personalized_original
,homepage_last_seen_original
,homepage_trends_original
, - other:
category_original
,news_original
,discounted_original
.
Click Event ¶
You should report a click event for any click interaction with search results.
Click event example
{
"type": "click",
"tracker_id": "1234-5678",
"client_id": 6667519810961010000,
"local_timestamp": 1552403218,
"id": 6667521051615376000,
"url": "https://www.eshop.com/search",
"path": "/search",
"title": "Demo shop page title",
"action": {
"type": "click",
"resource_identifier": "https://www.eshop.com/another-product"
}
}
In addition to Pageview event attributes (see "Pageview event" section above), Click event contains an additional action
attribute:
attribute | explanation |
---|---|
type REQUIRED |
Must contain value click . |
resource_identifier optional |
Identifier of the clicked item, which points to a clicked item from the search results / recommendation. If the type of the clicked item is query , resource_identifier should contain its title. Otherwise, it should contain item identity exactly as it is reported in other lists (Autocomplete, Search Results, Recommendation). Most typically, this will be item's url. |
Click Event with explicit Attributions (deprecated) ¶
Click event may contain attribution information defined also by Attributions.
Click event example with attribution (deprecated)
{
"type": "click",
"tracker_id": "1234-5678",
"client_id": 6667519810961010000,
"local_timestamp": 1552403218,
"id": 6667521051615376000,
"url": "https://www.eshop.com/search",
"path": "/search",
"title": "Demo shop page title",
"action": {
"type": "click",
"attributions": [
{
"event_id": 6667520098487994000,
"list": "Search Results",
"item_position": 3
}
]
}
}
In addition to Pageview event attributes (see "Pageview event" section above), Click event with Attribution contains an additional action
attribute:
attribute | explanation |
---|---|
type REQUIRED |
Must contain value click . |
attributions deprecated |
Explicit definition of attributions. |
You can define attributions explicitly by using attributions
in action
field of the event. Here, the attributions point to a previously reported pageview with search results by referring to its identifier (event_id
) and position of list item.
If the attribution
is given, it should contain a list of attributions following this structure:
attribute | explanation |
---|---|
event_id REQUIRED |
Identifier of the previously reported pageview with search results / recommendation, where the click happened. |
list REQUIRED |
Name of the list, where the item is clicked. |
item_position REQUIRED |
Position of the clicked item in list. |
Conversion event ¶
In case of a conversion, you should send a "click" event, with a different "action.type" value.
Conversion event example
{
"type": "click",
"tracker_id": "1234-5678",
"client_id": 6667519810961010000,
"local_timestamp": 1552403452,
"id": 6667522057510804000,
"url": "https://www.eshop.com/cautare",
"path": "/search",
"title": "Demo shop page title",
"action": {
"type": "buy",
"resource_identifier": "https://www.eshop.com/another-product"
}
}
Anything different from action type "click" is considered a conversion (e.g., "buy", "add-to-favorites", "add-to-comparison"). Please, do not forget to provide either attributions
or resource_identifier
(see "Click event" section above).
Transaction event ¶
To report user purchases, you may use a transaction event, which contains all the items with their quantities and applied discounts.
Transaction event example
{
"type": "transaction",
"tracker_id": "1234-5678",
"client_id": 6667519810961010000,
"local_timestamp": 1598019019,
"id": 6667520098487994000,
"url": "https://www.eshop.com/purchase",
"path": "/purchase",
"title": "Demo shop shopping cart",
"items": [
{
"title": "A product",
"url": "https://www.example.com/a-product",
"count": 1,
"total_price": 19,
"was_discounted": false,
"was_volume_discounted": false
},
{
"title": "Other product",
"url": "https://www.example.com/other-product",
"count": 3,
"total_price": 33,
"was_discounted": true,
"was_volume_discounted": false
}
]
}
Each transaction must contain a list of items that were purchased. Each item is a hash with the following key-value pairs:
key | explanation |
---|---|
title optional |
Title of the product. |
url REQUIRED |
Url of the product. |
count REQUIRED |
Quantity of the product within purchase. |
total_price REQUIRED |
Price of the product after taking into account quantity, discounts, and volume discounts (e.g. product with price 10 was added to basket 3 times, thus total_price is 30 ). |
was_discounted REQUIRED |
Determines, whether the product was discounted (true or false). |
was_volume_discounted REQUIRED |
Determines, whether the product was discounted based on the quantity within purchase (true or false). |
Support
Troubles? Cannot get it to work? Contact us at support@luigisbox.com, we are glad to help!