Analytics Events and Properties - SearchStax


This section describes how to add SearchStax® Analytics Events from Measured Search® to the Javascript of your search page.

Javascript Library

Your search page reports events through a javascript function on the web page.

Paste the following script before the ending body tag in your search pages. The script loads a javascript function, _msq.push(), that sends HTML event messages to your SearchStax Analytics App.

<script type="text/javascript"> 
var _msq = _msq || []; //declare object

(function() { var ms = document.createElement('script'); ms.type = 'text/javascript'; ms.src = 'https://static.searchstax.com/js/ms2.js'; var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ms, s); })(); 
</script>

Track Searches and Impressions

To track queries (and the search engine's performance against the queries), use _msq.push() to dispatch a track event as part of parsing the response document.

_msq.push(['track', { 
   key: "4Qp1Sv9MnALbAGbixW9ZaWrHxpbfwm6i", 
   user: "smith123", 
   session: "XDJFNS355FGDFVVDFG", 
   query: "Steve Jobs – San Francisco, CA", 
   shownHits: 10, 
   totalHits: 1890, 
   latency: 150, 
   pageNo: 1, 
   impressions: impressions
}]);
Property Description Example
key:
required
string
This is the unique analytics app key as seen in the SearchStax dashboard. '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. If omitted, some analytics features cannot be fully reported. 'XDJFNS355FGDFVVDFG'
query:
required
string
The query string from your search page, or q from the response document. 'Steve Jobs - San Francisco, CA'
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
experiment:
optional
string
Reserved for future use in the context of A/B experimental comparison.
impressions:
optional
array
Array of dictionaries, each describing a search result "impression." See example below.

The optional array of impression dictionaries lets the Analytics App track the documents that were offered to the user as search results, whether the user clicked on them or not. The dictionaries take this form:

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

where cDocId is the document ID; cDocTitle is the document title; and position 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 5th page is in position 41.

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.

<a onClick="_msq.push(['trackClick', { 
   session: 'XDJFNS355FGDFVVDFG', 
   key: '4Qp1Sv9MnALbAGbixW9ZaWrHxpbfwm6i', 
   query: 'Steve Jobs', 
   position: 4, 
   cDocId: 'http://mycompany.com/steve-jobs/', 
   cDocTitle: 'Steve Jobs', 
   pageNo: 1, 
   shownHits: 10, 
   totalHits: 1890
   lat: '33.916',
   lon: '-118.404',
   user_lat: '33.916',
   user_lon: '-118.404'        
 }]);" href="'http://mycompany.com/steve-jobs/">Steve Jobs</a>
Property Description Example
key:
required
string
This is the unique analytics app key as seen in the SearchStax dashboard. '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. If omitted, some analytics features cannot be fully reported. 'XDJFNS355FGDFVVDFG'
query:
required
string
The query string from your search page, or q from the response document. 'Steve Jobs - San Francisco, CA'
cDocId:
required
string
The document ID from the response document. 'http://mycompany.com/steve-jobs/'
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. 'Steve Jobs'
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. 41
pageNo:
optional
number
The page number of the displayed results, from the response document. 1
pageUrl:
optional
string
The URL of the result, from the response document. 'http://mycompany.com/steve-jobs/'
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
lat:
optional
string
Latitude (reserved for future development.) '33.916'
lon:
optional
string
Longitude (reserved for future development.) '-118.404'
user_lat:
optional
string
User latitude (reserved for future development.) '33.916'
user_lon:
optional
string
User Longitude (reserved for future development.) '-118.404'
experiment:
optional
string
Reserved for future use in the context of A/B experimental comparison.

Track Shopping Cart Additions

Use the addToCart event to track shopping cart additions.

<a onClick="_msq.push(['addToCart', { 
    category: 'Footwear',
    id: '123-456-789',
    sku: 'UGG-BB-PUR-06',
    name: 'UGG boots',
    key: '4Qp1Sv9MnALbAGbixW9ZaWrHxpbfwm6i',
    pageUrl: 'http://my.store.com/boots/UGG1.asp',
    price: 69.95,
    quantity: 7,
    session: 'XDJFNS355FGDFVVDFG',
    user: 'smith123'   
}]);" href="'http://mycompany.com/cart/">Add to cart</a>
Property Description Example
key:
required
string
This is the unique analytics app key as seen in the SearchStax dashboard. '4Qp1Sv9MnALbAGbixW9ZaWrHxpbfwm6i'
session:
required
string
The ID of the web session or mobile application session. 'XDJFNS355FGDFVVDFG'
user:
required
string
A token identifying the webpage user. 'smith123'
category:
required
string
The product category from the response document. 'Footwear'
id:
required
string
This is the item ID value, from the response document. '123-456-789'
sku:
required
string
This is the SKU value, from the response document. 'UGG-BB-PUR-06'
name:
required
string
The item name, from the response document. 'UGG boots'
pageUrl:
required
string
The URL of the web page that describes this item. 'http://my.store.com/boots/UGG1.asp'
price:
required
number
The price of the item. You determine the semantics. SearchStax expects a number with two decimal places. 69.95
quantity:
required
number
The number of items ordered. SearchStax expects an integer. 7
experiment:
optional
string
Reserved for future use in the context of A/B experimental comparison.

Track Transactions

When the user commits to a purchase, send an addTransaction event to the Analytics App. This data differs from the addToCart event only in the event name.

_msq.push(['addTransaction', { 
    category: 'Footwear',
    id: '123-456-789',
    sku: 'UGG-BB-PUR-06',
    name: 'UGG boots',
    key: '4Qp1Sv9MnALbAGbixW9ZaWrHxpbfwm6i',
    pageUrl: 'http://my.store.com/boots/UGG1.asp',
    price: 69.95,
    quantity: '7',
    session: 'XDJFNS355FGDFVVDFG',
    user: 'smith123'   
}]);
Property Description Example
key:
required
string
This is the unique analytics app key as seen in the SearchStax dashboard. '4Qp1Sv9MnALbAGbixW9ZaWrHxpbfwm6i'
session:
required
string
The ID of the web session or mobile application session. 'XDJFNS355FGDFVVDFG'
user:
required
string
A token identifying the webpage user. 'smith123'
category:
required
string
The product category from the response document. 'Footwear'
id:
required
string
This is the item ID value, from the response document. '123-456-789'
sku:
required
string
This is the SKU value, from the response document. 'UGG-BB-PUR-06'
name:
required
string
The item name, from the response document. 'UGG boots'
pageUrl:
required
string
The URL of the web page that describes this item. 'http://my.store.com/boots/UGG1.asp'
price:
required
number
The price of the item. You determine the semantics. SearchStax expects a number with two decimal places. 69.95
quantity:
required
number
The number of items ordered. SearchStax expects an integer. 7
experiment:
optional
string
Reserved for future use in the context of A/B experimental comparison.

Track Feedback

Was the item relevant to the search or not? You can put approve/disapprove icons under each result. SearchStax will collect and keep track of clicks on these icons using the trackFeedback event.

<a onClick="_msq.push(['trackFeedback', {
    key: '4Qp1Sv9MnALbAGbixW9ZaWrHxpbfwm6i',
    query: 'Steve Jobs - San Francisco, CA',
    cDocId: 'http://mycompany.com/steve-jobs/',
    cDocTitle: 'Steve Jobs'
    position: 41,
    pageNo: 1,
    pageUrl: 'http://mycompany.com/steve-jobs/',
    shownHits: 10,
    totalHits: 1890,
    user: 'smith123',
    session: 'XDJFNS355FGDFVVDFG',
    relevant: 0,
}]);" href="http://mycompany.com/steve-jobs/">Steve Jobs</a>
Property Description Example
key:
required
string
This is the unique analytics app key as seen in the SearchStax dashboard. '4Qp1Sv9MnALbAGbixW9ZaWrHxpbfwm6i'
session:
required
string
The ID of the web session or mobile application session. 'XDJFNS355FGDFVVDFG'
user:
required
string
A token identifying the webpage user. 'smith123'
query:
required
string
The query string from your search page, or q from the response document. 'Steve Jobs - San Francisco, CA'
cDocId:
required
string
The document ID from the response document. 'http://mycompany.com/steve-jobs/'
cDocTitle
required
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. 'Steve Jobs'
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. 41
pageNo:
required
number
The page number of the displayed results, from the response document. 1
pageUrl:
required
string
The URL of the result, from the response document. 'http://mycompany.com/steve-jobs/'
shownHits:
required
number
The number of hits shown in the response document. 10
totalHits:
required
number
The number of hits in the index, from the response document. 1890
relevant:
required
number
SearchStax will interpret 1 as relevant to your search, 0 as not relevant. 0
experiment:
optional
string
Reserved for future use in the context of A/B experimental comparison.