Instructions to send queries information using the Javascript Tagging Library.
Query data can be sent to Empathy using the trackQuery function including the following parameters:
trackQuery(terms, results, page, options, callback) |
Parameter | Description | Data Type | Mandatory |
---|---|---|---|
terms | The query typed by the user | String | Yes |
results | Number of results returned by the search engine | Integer | Yes |
page | The page number | Integer | Yes |
options | Object that may contain information about filters and other data like session and userID | Object | No* |
callback | Function that will be executed after sending data | Function | No |
*This parameters are not mandatory for the service but necessary for the statistics |
The options object should contains additional parameters not passed as parameters in function call:
{ lang: LANGUAGUE, scope: SCOPE, store: STORE, catalog: CATALOG, section: SECTION, user: USER_ID, session: SESSION_ID } |
Parameter | Description | Data Type | Mandatory |
---|---|---|---|
FILTERS: possible values (and other custom filters if applicable) will be provided by Empathy | |||
lang | Language identifier (es, en...) | String | No |
scope | Scope identifier (desktop, mobile, android app, iOS app...) | String | No |
store | Store value if it is required for the project | String | No |
catalog | Catalog value if it is required for the project | String | No |
section | Section value if it is required for the project | String | No |
TRACKING: user and session identifiers should use the UUID format | |||
user | UserID used for user based services | String | No |
session | SessionID used for user based services | String | No |
The callback function receives an object with the following content. Also receives params sent in options.
{ totalHits: results, page: page, q: terms, referrer: document.referrer } |
/** * This example suppose that the provided scope is 'desktop' and the parameter to be included in the options parameter is the lang * parameter with value 'en' . UserID and SessionID are also included. **/ var options = { lang:'en', scope: 'desktop', session: 'q1w2e3r4t5y6', user: 'u1s2e3r' } empathyTAG.trackQuery('test', 10, 1, options, function(responseData){ alert('test'); }); |
/** * This example suppose that the provided scope is 'desktop' and the parameter to be included in the options parameter is the lang * parameter with value 'en' . UserID and SessionID are also included. **/ var options = { lang:'en', scope: 'desktop', session: 'q1w2e3r4t5y6', user: 'u1s2e3r' } empathyTAG.trackQuery('test', 10, 1, options); |
In most of the cases, you should implement one of these solutions to prevent receiving partial queries:
Prevent partial queries applying a delay before sending the trackQuery information, the delay time in the following example will be 2000 ms (2 seconds).
var _timeoutID; var options = { lang:'en', scope: 'desktop', session: 'q1w2e3r4t5y6', user: 'u1s2e3r' } window.clearTimeout(_timeoutID); _timeoutID = window.setTimeout(function(){ empathyTAG.trackQuery('test', 10, 1, options, function(responseData){ alert('test'); }); },2000); |
Prevent partial queries filtering the query length to be considered as valid. For this example, it will be used 3 characters as minimal length.
//This variable should be filled with the query typed by the user var userQuery = 'test'; var _timeoutID; var options = { lang:'en', scope: 'desktop', session: 'q1w2e3r4t5y6', user: 'u1s2e3r', } if (userQuery.length > 3){ window.clearTimeout(_timeoutID); _timeoutID = window.setTimeout(function(){ empathyTAG.trackQuery('test', 10, 1, options, function(responseData){ alert('test'); }); },2000); } |
Remember send queries when search engine returns 0 results. It's very important for future actions in search engine.
/** * This example suppose that the provided scope is 'testscope' and the parameter to be included in the options parameter is the lang * parameter with value 'en' **/ var options = { lang:'en', scope: 'desktop', session: 'q1w2e3r4t5y6', user: 'u1s2e3r' } empathyTAG.trackQuery('test', 10, 0, options); |
Blank queries: Do not send a query without characters. Usually when users click in search button without write nothing in search box.
In this case be careful to not send the placeholder text (i.e. "Search...")