Search Analytics API


This page describes how to add SearchStax® Analytics Events to the Javascript of your search page. This is a required step for the collection of user events at your search site. The events, in turn, make it possible to track analytics metrics to test the effect of proposed changes to your site.

Contents of this page:

Javascript Library

Your search page would track searches, clicks, and user feedback and send the information to your Site Search App.

Paste the following script in the head section of your Search Page:

 <script type="text/javascript">
    var _msq = _msq || []; //declare object
    var analyticsBaseUrl = 'https://app.searchstax.com';
    var 
    (function () {
      var ms = document.createElement("script");
      ms.type = "text/javascript";
      ms.src = "https://static.searchstax.com/studio-js/v2/js/studio-analytics.js";
      var s = document.getElementsByTagName("script")[0];
      s.parentNode.insertBefore(ms, s);
    })();
 </script>

Change the 'analyticsBaseUrl' based on the Analytics URL shown in the “Analytics API” section of your App within Site Search App Management.

  

Events

An “event” is a user action on your search page, such as searching for a keyword or clicking on a search result. SearchStax supports the following event messages:

An event message is a wrapper for a list of property-value pairs. The values are the data that SearchStax tracks and analyzes.

Each type of event has its own set of required properties, which are detailed below. The following are the common properties across all events:

PropertyDescriptionExample
key:
required
string  
This is the unique analytics app key as shown in the “Analytics API” tab of your App within Site Search App Management ‘4Qp1Sv9MnALbAGbixW9ZaWrHxpbfwm6’
session:
required
string  
The ID of the web session or mobile application session. If omitted, some analytics features cannot be fully reported.‘XDJFNS355FGDFVVDFG’

  

  

Track Searches and Impressions

To track searches, use _msq.push() and dispatch a track event as part of parsing the response document.

_msq.push(['track', { 
   key: "4Qp1Sv9MnALbAGbixW9ZaWrHxpbfwm6i", 
   user: "smith123", 
   session: "XDJFNS355FGDFVVDFG", 
   query: "sitecore plugin", 
   shownHits: 10, 
   totalHits: 1890, 
   latency: 150, 
   pageNo: 1, 
   impressions: impressions
}]);

PropertyDescriptionExample
key:
required
string
Unique Analytics API Key‘4Qp1Sv9MnALbAGbixW9ZaWrHxpbfwm6i’
user:
optional
string
A token identifying the webpage user. This datum is stored but is not currently used.‘smith123’
session:
required
string
The ID of the web session or mobile application session. ‘XDJFNS355FGDFVVDFG’
query:
required
string
The query string from your search page, or q from the response document.‘sitecore plugin’
shownHits:
optional
number
The number of hits shown in the response document.10
totalHits:
optional
number
The number of hits in the index, from the response document.

Note: To track searches that returned no results, set totalHits to 0.
1890
latency:
optional
number
The number of milliseconds to execute a search. You define the semantics. (One possibility is to use Qtime from the response document). Without this value, Analytics will not calculate average latency.150
pageNo:
optional
number
The page number of the displayed results, from the response document.1
impressions:
optional
array
An array of dictionaries, each describing a search result “impression.”This is required if you would like to track impressions. See the example below.

The optional array of impression dictionaries lets the Analytics App track the documents that were displayed to the user as search results, whether the user clicked on them or not. Use a javascript array to catalog the search results in the following format:

var impressions = [
   {'cDocId': 'aDocId1', 'cDocTitle': 'aDocTitle1', 'position': 1},
   {'cDocId': 'aDocId2', 'cDocTitle': 'aDocTitle2', 'position': 2},
];

where aDocId1 is the ID of the document in position 1 and aDocTitle1 is the title of the document in position 1. The position parameter is the absolute position of the document in the full result list. (If we’re showing ten items per page, the first result on the fifth page is in position 41.)

For example, your application might respond to a query by (1) passing the query to Solr, (2) parsing the result document, and (3) generating a search-page update containing a script like this one at the end of the <body> section:

<script>
    var track = {
    "key": "imDMrs56aTaDJc6jihDejUkDZYj3Gm8riJHlR0",
    "query": "sitecore",
    "shownHits": 3,
    "totalHits": 12,
    "pageNo": 1,
    "latency": 1,
    "session": "Ll5UDHUQHccphnlb7lp6sQIo5",
    "impressions": [
      {"cDocId": "https://www.searchstax.com/videos/solr-cloud-best-practices-sitecore/",
        "cDocTitle": "Sitecore Solr Best Practices - SolrCloud SUGLA Meetup | SearchStax",
        "position": 1
      },
      {
        "cDocId": "https://www.searchstax.com/solutions/sitecore-solr/",
        "cDocTitle": "Sitecore Solr Search: Get fast and relevant search results | SearchStax",
        "position": 2
      },
      {
        "cDocId": "https://www.searchstax.com/case-studies/sitecore-solr-search-azure-isango/",
        "cDocTitle": "Case Study Isango!",
        "position": 3
      }
    ],
  }}
    if(track.query != '') {
        _msq.push(['track', track]);
}
</script>


In this way, your application can push a description of the search to your Analytics App by automatically calling the _msq.push() function as soon as the updated search page is viewed by the user.

  

  

Track Clicks

To start generating data around click-through events, search quality and relevance, have _msq.push() send trackClick events to the Analytics App.

In your search-results page, add an on-click event in the link to each search result.

_msq.push(['trackClick', { 
   session: 'Ll5UDHUQHccphnlb7lp6sQIo5', 
   key: 'imDMrs56aTaDJc6jihDejUkDZYj3Gm8riJHlR0', 
   query: 'sitecore', 
   position: 2, 
   cDocId: 'https://www.searchstax.com/solutions/sitecore-solr/', 
   cDocTitle: 'Sitecore Solr Search: Get fast and relevant search results | SearchStax', 
   pageNo: 1, 
   shownHits: 3, 
   totalHits: 12}]);

PropertyDescriptionExample
key:
required
string
Unique Analytics API Key‘4Qp1Sv9MnALbAGbixW9ZaWrHxpbfwm6i’
user:
optional
string
A token identifying the webpage user. This datum is stored but is not currently used.‘smith123’
session:
required
string
The ID of the web session or mobile application session. ‘XDJFNS355FGDFVVDFG’
query:
required
string
The query string from your search page, or q from the response document.‘sitecore plugin’
cDocId:
required
string
The document ID from the response document.https://www.searchstax.com/solutions/sitecore-solr/
cDocTitle
optional
string
The document title from the response document. Note: In some applications, the document title may change. Analytics can be calculated as long as cDocID remains constant.‘Sitecore Solr Search: Get fast and relevant search results | SearchStax’
position:
required
number
Absolute position of the document in the full list of results. If we’re showing ten items per page, the first result on the 5th page is position in position 41. First item on the first page has position as 141
pageNo:
optional
number
The page number of the displayed results, from the response document.1
pageUrl:
optional
string
The URL of the page that is sending the tracking request‘https://searchstudio.searchstax.com/search’
shownHits:
optional
number
The number of hits shown in the response document.10
totalHits:
optional
number
The number of hits in the index, from the response document.1890

  

  

Track Search Satisfaction

SearchStax provides the ability to collect qualitative feedback about the search experience using trackSearchSatisfaction.

_msq.push(['trackSearchSatisfaction', {
    key: '4Qp1Sv9MnALbAGbixW9ZaWrHxpbfwm6i',
    email: 'user1@searchstax.com',
    score: 10,
    comments: 'Very good search experience'
    session: 'XDJFNS355FGDFVVDFG'
}]);

PropertyDescriptionExample
key:
required
string
Unique Analytics API Key.‘4Qp1Sv9MnALbAGbixW9ZaWrHxpbfwm6i’
session:
required
string
The ID of the web session or mobile application session.‘XDJFNS355FGDFVVDFG’
email:
optional
string
Email ID of the user submitting the feedback‘user123@searchstax.com’
comments:
optional
string
Feedback about the search experience as a comment‘Very good search experience’
score:
required
string
0-10 score, rating the search experience10

The searchFeedback events are used to compute the NPS score (Net {Promoter Score) for your Search Application.

  

  

Debugging Analytics APIs

You can use any browser debugging tools to debug the calls being made to the Analytics server. In Chrome, you can right click on the page, click on “Inspect” and look at the Network tab for calls made to the ‘analyticsBaseUrl’. Have ‘Preserve log’ checked so you can track clicks as they open in new pages.

The Analytics APIs will look like:

https://app.searchstax.com/api/v2/track/?data=eyJldmVudCI6Il9zZWFyY2hjbGljayIsInByb3BlcnRpZXMiOnsia2V5IjoiaW1ETXJzNTZhVGFESmM2amloRGVqVWtEWllqM0dtOHJpSkhsUjBWMVM1OCIsInF1ZXJ5Ijoic2l0ZWNvcmUiLCJzaG93bkhpdHMiOjksInRvdGFsSGl0cyI6MTMxLCJwYWdlTm8iOjEsImxhdGVuY3kiOjExLCJzZXNzaW9uIjoiNnNmN09GSWJRSlp1cU92ZU1VdUkyOW5SMSIsImNEb2NJZCI6Imh0dHBzOi8vd3d3LnNlYXJjaHN0YXguY29tL3NvbHV0aW9ucy9zaXRlY29yZS1zb2xyLyIsImNEb2NUaXRsZSI6IlNpdGVjb3JlIFNvbHIgU2VhcmNoOiBHZXQgZmFzdCBhbmQgcmVsZXZhbnQgc2VhcmNoIHJlc3VsdHMgfCBTZWFyY2hTdGF4IiwicG9zaXRpb24iOjEsIl92aWQiOiIxYzkwZWQ3MS1lZjljLTVlNjAtNGJlNS1jODI4OWYwMWJkYzkiLCJ0dCI6MTYxNzA2NjQwODAxMiwicGFnZVVybCI6Imh0dHBzJTNBJTJGJTJGd3d3LnNlYXJjaHN0YXguY29tJTJGc2VhcmNoJTNGc2VhcmNoU3R1ZGlvUXVlcnklM0RzaXRlY29yZSUyNnN0eWxlJTNEdHJ1ZSUyNmZhY2V0cyUzRCUyNnNvcnQlM0QlMjZzdGFydCUzRDAlMjZmYWNldENvbnRlbnQlMjUyMFR5cGUlM0QxJTI2ZmFjZXRBdXRob3IlM0QxJTI2ZmFjZXRLZXl3b3JkcyUzRDEifX0=

The argument to “data” is Base64 encoded properties. You can use online base64 decoders like https://www.base64decode.org/ to decode them to view the JSON data being passed