Tracking API (Javascript)

Updated

The JavaScript Tracking API sends analytics events to the tracking ingestion endpoint.

Endpoint

  • Method: GET or POST
  • Endpoint pattern: https://<analytics-host>/api/v2/track/

UI Navigation

Find this endpoint and tracking key in Site Search > App Settings > All APIs > Analytics.

Analytics endpoint and tracking key panel in Site Search app settings.

Authentication Model

This endpoint uses payload-based key validation, not token headers.

  • Required payload field: properties.key
  • Transport field: data (Base64-encoded JSON event payload)

Request Parameters

Name Required Type Description
data Yes query string Base64-encoded JSON event payload sent to /api/v2/track/ by the JavaScript analytics library.
key Yes payload field Tracking key inside properties.key within the decoded event payload.

Request Example 

curl -sS --get \
  --data-urlencode "data=<base64-encoded-event-json>" \
  "https://<analytics-host>/api/v2/track/"

Decoded payload shape example: 

{
  "event": "search",
  "properties": {
    "key": "<tracking-key>",
    "query": "site search"
  }
}

Event Examples

Use _msq.push() to send one analytics event at a time. Include language and model when you want language-scoped analytics or profile-level reporting.

Note: Both dash and underscore language-code variants are accepted and normalized automatically, so use the language code your integration sends.

Track Search Results

Use this pattern after search results render to capture the query, displayed results, and impressions. 

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

Use an impressions array like this: 

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

Track Smart Answers

Use this pattern when the search UI returns an AI-generated answer for a question query. 

_msq.push(['trackquestionanswer', {
   key: "4Qp1Sv9MnALbAGbixW9ZaWrHxpbfwm6i",
   session: "XDJFNS355FGDFVVDFG",
   question: "what versions of solr does searchstax support",
   is_question: "true",
   answer: "SearchStax supports a variety of Apache Solr versions for its Managed Search service. As of the latest information, the supported versions include: ...",
   language: "en",
   model: "CorpsiteModel"
}]);

Track Related Searches

Use this pattern when your UI renders related-search suggestions for a query. 

_msq.push(['trackRelatedSearch', {
   key: "4Qp1Sv9MnALbAGbixW9ZaWrHxpbfwm6i",
   user: "smith123",
   session: "XDJFNS355FGDFVVDFG",
   query: "sitecore plugin",
   shownHits: 10,
   latency: 150,
   impressions: impressions,
   language: "en",
   model: "CorpsiteModel"
}]);

Use an impressions array like this: 

var impressions = [
   {'relatedSearch': 'relatedTerm1', 'position': 1},
   {'relatedSearch': 'relatedTerm2', 'position': 2},
];

Track Clicks

Use this pattern when a user clicks a search result document. 

_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,
   language: "en",
   model: "CorpsiteModel"
}]);

Track Related Search Clicks

Use this pattern when a user clicks a related-search suggestion. 

_msq.push(['trackRelatedSearchClick', {
   session: 'Ll5UDHUQHccphnlb7lp6sQIo5',
   key: 'imDMrs56aTaDJc6jihDejUkDZYj3Gm8riJHlR0',
   query: 'sitecore',
   position: 2,
   relatedSearch: 'sitecore 7',
   pageNo: 1,
   shownHits: 3,
   totalHits: 12,
   language: "en",
   model: "CorpsiteModel"
}]);

Track Search Satisfaction

Use this pattern to collect qualitative feedback about the search experience. 

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

Response Notes

Successful tracking ingestion returns 204 No Content with an empty body.

HTTP Status Codes and Error Handling

HTTP Code When It Happens Typical Response Body What to Do
204 Event accepted Empty body No retry needed
422 Missing or invalid payload, malformed Base64 or JSON, or invalid key Validation failure response (often empty body) Correct payload and retry
429 Shared app-level rate or plan limit condition Too-many-requests response Retry with backoff

Pagination

Not applicable. Tracking ingestion endpoints do not return paged result sets.

Rate Limits and Backoff

  • Shared app-level guidance: 20+ requests/second.
  • Retry-After is not guaranteed for shared limit responses.
  • Use retry backoff for transient 429 conditions.

Shared API Foundations

Use these shared references for authentication, request and response structure, and pagination behavior used across Site Search APIs:

Articles in this section