Search Events API - SearchStax


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 reports user-generated 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>

Events

An "event" is a user action on your search page, such as a mouse-click on a link or button. SearchStax supports the following event messages:

Event Properties

An event message is a wrapper for a list of property-value pairs. The values are the data that SearchStax tracks and analyzes. For instance, this is an event URL describing a user query:

    https://app.searchstax.com/api/v2/track/?data=eyJldmVudCI6Il9zZWFyY2
    giLCJwcm9wZXJ0aWVzIjp7ImtleSI6IjlyN3dSbnN2QUFyMHltZnNkOVZDSWI2eWtyd0Z0QURySVllT
    0E4UUZJRGciLCJxdWVyeSI6ImZvbyIsInNob3duSGl0cyI6MSwidG90YWxIaXRzIjoxLCJwYWdlTm8i
    OjEsImxhdGVuY3kiOjUyMiwiX3ZpZCI6ImZiZjIwZWY3LWU1Y2YtMzcyOC1mMTZiLTk2NjNlZWU3NjU
    0MyIsInR0IjoxNTAzOTM5MDkxMTg5LCJwYWdlVXJsIjoiaHR0cCUzQSUyRiUyRjk3MjUzMTg5Lm5ncm
    9rLmlvJTJGZW4lMkZzZWFyY2gtcmVzdWx0cy5waHAlM0ZpZSUzRFVURi04JTI2cSUzRGZvbyJ9fQ==
The data contains the properties of the event expressed as a JSON document. The data has been base64 encoded to protect URL values from character-encoding transformations as the message crosses the Internet. Decoded, the data says:

{"event":"_search","properties":
    {"key":"9r7wRnsvAAr0ymfsd9VCIb6ykrwFtADrIYeOA8QFIDg",
    "query":"test",
    "shownHits":10,
    "totalHits":573,
    "pageNo":1,
    "latency":2809,
    "pageUrl":"http%3A%2F%2F97253189.test.io%2Fen%2Fsearch-results.php%3Fie%3DUTF-8%26q%3Dtest"}}

This event reports that the user searched for "test". The search engine got 573 hits, of which it returned 10 in the first page. This required 2.8 seconds.

Each type of event has its own set of required properties, which are detailed below.

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
Store this event under the named boost experiment. boost-high-price
impressions:
optional
array
Optional 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 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.)

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
Store this event under the named boost experiment. boost-high-price

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
Store this event under the named boost experiment. boost-high-price

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
Store this event under the named boost experiment. boost-high-price

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
Store this event under the named boost experiment. boost-high-price

Questions?

Do not hesitate to contact the SearchStax Support Desk.