NAV Navbar

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 usually triggered

All events are expected to be HTTP POST-ed to https://api.luigisbox.com.

List event

You should report every list of products shown to the user to our event API. Here, you can see an example of a pageview ("pv") event, which includes a "Search Results" list of products.

List event example

{
 "type": "pv",
 "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).

Every item should have a "type" associated (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.

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.

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",
   "attributions": [
     {
       "event_id": 6667520098487994000,
       "list": "Search Results",
       "item_position": 3
     }
   ]
 }
}

This event must contain attribution information, which points to a previously reported pageview with search results by referring to its identifier and position of list item.

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",
   "attributions": [
     {
       "event_id": 6667520098487994000,
       "list": "Search Results",
       "item_position": 3
     }
   ]
 }
}

Anything different from action type "click" is considered a conversion (e.g., "buy", "add-to-favorites", "add-to-comparison").

Support

Troubles? Cannot get it to work? Contact us at support@luigisbox.com, we are glad to help!