NAV

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:

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
typeREQUIRED 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_idREQUIRED The site tracker_id from Luigi's Box Analytics.
client_idREQUIRED An identifier of the user, preferably numeric. Make sure that it is unique for each distinct user.
customer_idoptional An identifier of the logged in user (in your system). Make sure that it is unique for each registered user.
local_timestampoptional Local timestamp in seconds.
app_versionoptional Version string of your integration.
idREQUIRED Globally unique ID of the event.
urlrecommended 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.
pathoptional Path part of the URL.
titleoptional Title of the page.
refereroptional Referer URL.
contextoptional 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_grantedoptional Set true, if a user has granted consent for personalization.
from_list_idoptional 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
itemsREQUIRED List of items in the list.
queryREQUIRED 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
titleREQUIRED Title of the item.
typeREQUIRED 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.
urlREQUIRED Identifier of the item, generally url.
positionREQUIRED Position of the item in a list.
priceoptional 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
RecommenderClientIdREQUIRED 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).
RecommendationIdREQUIRED 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.
ItemIdsoptional List of input items of a recommendation request (item_ids from recommendation request).
Recommenderoptional Name of the recommender (recommender from recommendation result).
Typeoptional Type of the recommender (recommendation_type from recommendation result).
_Variantoptional Determines variant in A/B testing (e.g., Original, Luigis).

How to set RecommenderClientId

RecommenderClientId usually consists of three parts:

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:

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
typeREQUIRED Must contain value click.
resource_identifieroptional 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
typeREQUIRED Must contain value click.
attributionsdeprecated 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_idREQUIRED Identifier of the previously reported pageview with search results / recommendation, where the click happened.
listREQUIRED Name of the list, where the item is clicked.
item_positionREQUIRED 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
titleoptional Title of the product.
urlREQUIRED Url of the product.
countREQUIRED Quantity of the product within purchase.
total_priceREQUIRED 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_discountedREQUIRED Determines, whether the product was discounted (true or false).
was_volume_discountedREQUIRED 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!