Javascript Tagging Library: Track Query

Owned by Lara Menéndez García (Unlicensed)
Last updated: May 15, 2019
3 min read

Overview

Instructions to send queries information using the Javascript Tagging Library.

Step-by-step guide

Query data can be sent to Empathy using the trackQuery function including the following parameters:

trackQuery(terms, results, page, options, callback)


trackQuery Parameters

ParameterDescriptionData TypeMandatory
termsThe query typed by the userStringYes
resultsNumber of results returned by the search engineIntegerYes
pageThe page numberIntegerYes
optionsObject that may contain information about filters and other data like session and userIDObjectNo*
callbackFunction that will be executed after sending dataFunctionNo

*This parameters are not mandatory for the service but necessary for the statistics

Options

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
}
ParameterDescriptionData TypeMandatory
FILTERS: possible values (and other custom filters if applicable) will be provided by Empathy
langLanguage identifier (es, en...)StringNo
scopeScope identifier (desktop, mobile, android app, iOS app...)StringNo
storeStore value if it is required for the projectStringNo
catalogCatalog value if it is required for the projectStringNo
sectionSection value if it is required for the projectStringNo
TRACKING: user and session identifiers should use the UUID format
userUserID used for user based servicesStringNo
sessionSessionID used for user based servicesStringNo


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
}


Code samples

Normal Usage

Specifying a callback parameter
/**
 * 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');
});
Without a callback (No functions will be executed after tracking the data)
/**
 * 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);

Best practices

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...")