Tracking Integration Guide
For a continuously optimization of the search quality it is mandatory to track the search results. When you use the QSC the most data is already tracked in the search backend.
- Timestamp
- Search Query
- Total hits for the query
- Pagination
- number of displayed results of the current page
- used filters with values
- used sorting
- displayed documents
- internal search time
- ip address
- user agent
- referrer
- session id
- request id
- user id
Tracking of search queries
In case the QSC is used, the most metrics for the search are tracked already by the backend.
- search query
- pagination
- sorting
- filtering
To identify the user and the search session there are different identifiers.
| identifier | description |
|---|---|
| requestId | identifies a search request. |
| userId | identifies the user permanently. Login, tracking cookie, ... |
| sessionId | identifies the user over a session. |
To correlate the tracking data with the searches, it is neccessary to send this identifiers also for each search request.
A lot of frameworks e.g. GraphQL are caching the search requests already in the frontend. In this case search requests can not be tracked in the server side. Because of this it is reommended to integrate a client side tracking library.
RequestId
All actions for a search term are enclosed by a requestId. When the user submit a new search a new requestId is generated. If the client creates no requestId the backend creates the requestId and return it in the response.
https://qsc-dev.quasiris.de/api/v1/search/lugina/suche?q=schuhe
{
"statusCode": 200,
"requestId" : "69e0320e-e2aa-4f1e-94f3-5a440c9f55db",
"result": {},
"time": 31,
"currentTime": "2021-05-26T06:00:12+0000",
"request": {}
}
The requestId 69e0320e-e2aa-4f1e-94f3-5a440c9f55db is automatically generated by the backend.
If the user is paginating, sorting, filtering the search result, the initial generated requestid must be sent for each request to the backend.
Example with Paging
{
"statusCode": 200,
"requestId" : "69e0320e-e2aa-4f1e-94f3-5a440c9f55db",
"result": {},
"time": 31,
"currentTime": "2021-05-26T06:00:12+0000",
"request": {}
}
Session Id
The session id identifies the user over a session. A session encloses multiple search requests and a new session is started after 30 minutes inactivity.
To easily identify the session a session cookie from the website can be used. If there are no existing session informations available the session handling can be handled manually.
User Id
The user id identifies the user permanently. In a online shop login data can be used. For example the name, email or customer number. The search don't require the real data. It is sufficient to send a hash value. It is just important that the hash value is always identical for the same user.
Tracking of user actions in the frontend
Not all relevant metrics can be tracked in the search backend. For example the click on a search result is not routed to the search backend and can not be tracked. In this cases a tracking must be integrated in the search frontend.
The tracking request are send by a http post request. In the example below the user searched for schuhe on page 1 and clicked the first document with the id 4711
curl -XPOST https://qsc-dev.quasiris.de/api/v1/analytics/lugina/product-reco -H "content-type: application/json" -d '
{
"type" : "document",
"requestId" : "04df50a2-4110-4a66-b1ff-a469bb94ad37",
"userId" : "579434e9-4c88-42b6-9f65-b79fc6f0d98d",
"sessionId" : "a9b2527f-69df-4b01-af54-3b51f0f892ee",
"q" : "schuhe",
"docId" : "4711",
"position" : 1,
"page" : 1
}'
| attributes | description |
|---|---|
| type | The tracking type. (types: document, facet, paging, query, sorting). |
| requestId | A unique id for the request. |
| userId | A unique id for the user. |
| sessionId | A unique id for the session. |
| q | The query. For a recommendation the id of the product must be used. |
| docId | A unique id for the document that was clicked. |
| position | The local position of the document of the current page that was clicked. The position starts at 1 not at 0. |
| page | The page of the document that was clicked. |
Use cases
In this section we show some example use cases for the tracking. The tenant lugina is used as an example and must be replaced by your tenant code.
Tracking clicks on documents
In this example a analytics event is send, in case of the user clicked a document in a search result page.
curl -XPOST https://qsc-dev.quasiris.de/api/v1/analytics/lugina/products -H "content-type: application/json" -d '
{
"type" : "clickDocument",
"requestId" : "04df50a2-4110-4a66-b1ff-a469bb94ad37",
"userId" : "579434e9-4c88-42b6-9f65-b79fc6f0d98d",
"sessionId" : "a9b2527f-69df-4b01-af54-3b51f0f892ee",
"q" : "schuhe",
"docId" : "4711",
"position" : 1,
"page" : 1
}'
| attributes | description |
|---|---|
| type | clickDocument - Click on a document |
| requestId | A unique id for the request. |
| userId | A unique id for the user. |
| sessionId | A unique id for the session. |
| q | The search query, which causes the result where document was clicked. |
| docId | A unique id for the document that was clicked. |
| position | The local position of the document of the current page that was clicked. The position starts at 1 not at 0. |
| page | The page of the document that was clicked. |
Tracking clicks on add to cart
In this example a analytics event is send, in case of the user clicked the add to cart button on the search result page.
curl -XPOST https://qsc-dev.quasiris.de/api/v1/analytics/lugina/products -H "content-type: application/json" -d '
{
"type" : "addToCart",
"requestId" : "04df50a2-4110-4a66-b1ff-a469bb94ad37",
"userId" : "579434e9-4c88-42b6-9f65-b79fc6f0d98d",
"sessionId" : "a9b2527f-69df-4b01-af54-3b51f0f892ee",
"q" : "schuhe",
"docId" : "4711",
"position" : 1,
"page" : 1
}'
| attributes | description |
|---|---|
| type | addToCart - Click on addToCart |
| requestId | A unique id for the request. |
| userId | A unique id for the user. |
| sessionId | A unique id for the session. |
| q | The search query, which causes the result where document was clicked. |
| docId | A unique id for the document that was clicked. |
| position | The local position of the document of the current page that was clicked. The position starts at 1 not at 0. |
| page | The page of the document that was clicked. |
Tracking clicks on Facets
In this example a analytics event is send, in case of the user clicked on a value of a facet on the search result page.
curl -XPOST https://qsc-dev.quasiris.de/api/v1/analytics/lugina/products -H "content-type: application/json" -d '
{
"type" : "clickFacet",
"requestId" : "04df50a2-4110-4a66-b1ff-a469bb94ad37",
"userId" : "579434e9-4c88-42b6-9f65-b79fc6f0d98d",
"sessionId" : "a9b2527f-69df-4b01-af54-3b51f0f892ee",
"q" : "schuhe",
"facetId" : "color",
"facetValue" : "red",
"position" : 1,
"page" : 1
}'
| attributes | description |
|---|---|
| type | clickFacet - Click on a facet |
| requestId | A unique id for the request. |
| userId | A unique id for the user. |
| sessionId | A unique id for the session. |
| q | The search query, which causes the result where the facet was clicked. |
| facetId | A unique id for the facet that was clicked. In QSC this is provided in the search result. |
| facetValue | The value of the facet that was clicked. |
| position | The position of the facet that was clicked. |
| page | The page of the facet that was clicked. |
Tracking Autocomplete suggest
Tracking visits or likes on a document
In this example a analytics event is send, in case a document was seen by user. It is not important, that a search result presented the document.
curl -XPOST https://qsc-dev.quasiris.de/api/v1/analytics/lugina/products -H "content-type: application/json" -d '
{
"type" : "visit",
"userId" : "579434e9-4c88-42b6-9f65-b79fc6f0d98d",
"sessionId" : "a9b2527f-69df-4b01-af54-3b51f0f892ee",
"docId" : "my-page-id"
}'
| attributes | description |
|---|---|
| type | visit - visit of the page |
| userId | A unique id for the user. |
| sessionId | A unique id for the session. |
| docId | The id of the document. |
To track a like, just set the type to the value "like".
curl -XPOST https://qsc-dev.quasiris.de/api/v1/analytics/lugina/products -H "content-type: application/json" -d '
{
"type" : "like",
"userId" : "579434e9-4c88-42b6-9f65-b79fc6f0d98d",
"sessionId" : "a9b2527f-69df-4b01-af54-3b51f0f892ee",
"docId" : "my-page-id"
}'