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).

client_id should identify each distinct user, regardless a user is logged in or not. You should always send customer_id once a registered user logs in. customer_id should be the same for a specific user across several sessions, however you do not have to use the exactly same identifier as in your system.

Pay special attention to local_timestamp and make sure that it is in seconds. A very common mistake that we see is that the timestamp is in milliseconds. If you send the timestamp in milliseconds, we will decode it to a date far in the future and drop the event as invalid.

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.

You can report Pageview and List event at once by setting type of the List event to pv. If you report more than one list on the same page (e.g., search results, autocomplete, recommendation), you have to set type to event on every event except the first one.

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.

You can use Search Results, Autocomplete and Recommendation as the name of a list. Use Autocomplete for "search-as-you-type" kinds of lists. Use Search Results to report either standard search or category listing (where query string is empty in favor of filters defining the category being shown). Finally, use Recommendation to report lists in any kinds of widgets, which are shown anywhere on your site (homepage, product detail etc.). Use filters to specify type of recommendation and other metadata.

In case of Autocomplete, do not send us partial queries while a user is still typing. Send us an Autocomplete list event only once user had stopped typing for a while and is actually evaluating results.

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.

You can report Pageview and List event at once by setting type of the List event to pv. If you report more than list on the same page (e.g., search results, autocomplete, recommendation), you have to set type to event on every event except the first one.

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 use original).

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.

url of the click event is optional. However, if you do not use url of the event, you have to provide resource_identifier inside the action.

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.

url of the conversion event is optional. However, if you do not use url of the event, you have to provide resource_identifier inside the action.

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!