Merge pull request #4 from AddSearch/stats-v2

Stats v2

Author: anttiai

README.md

@@ -70,11 +70,12 @@ client.suggestions('a', callback);
 client.setSuggestionsSize(20);
 ```
 
-#### Fetch custom field autocompletion
+#### Custom field autocompletion
 Custom fields autocomplete can be used for predictive search. For example, product names or categories can be
 suggested as the keyword is being typed in.
 ```js
-// Fetch custom field values starting with a specific prefix. In this example, results could be "adidas, apple, azure"
+// Fetch custom field values starting with a specific prefix In this example, fetch records 
+// starting with *a* from the *custom_fields.brand* field. Results could be "adidas, apple, azure"
 client.autocomplete('custom_fields.brand', 'a', callback);
 ```
 
@@ -86,57 +87,36 @@ client.setAutocompleteSize(20);
 
 #### Search with fuzzy matching
 ```js
-// Enable/disable fuzzy matching. Possible values true/false/"auto" (default: "auto")
-client.setFuzzyMatch(false);
+// Control fuzzy matching used for typo-tolerance
+// Possible values true/false/"auto" (default: "auto")
+client.setFuzzyMatch(false);  
 ```
 
-#### Collect analytics
+### Pagination
+Set page number, page size and sorting parameters. It's possible to order results by:
+- relevance (descending)
+- date (ascending or descending)
+- custom field value (ascending or descending. E.g. *custom_fields.price*)
 ```js
-// Control whether search queries are sent to your AddSearch Analytics Dashboard or not (default: true)
-client.setCollectAnalytics(false);
+// Defaults: page "1", pageSize "10", sortBy "relevance", sortOrder "desc"
+client.setPaging(page, pageSize, sortBy, sortOrder);
 ```
 
-#### Send click event to analytics
-When a search results is clicked, send the event to your AddSearch Analytics Dashboard. Information on clicks is used
-in your statistics and in the self-learning search algorithm.
-```js
-// Docid is the 32-character long id that is part of each hit in search results
-// Position is the position of the document that was clicked, the first result being 1
-client.searchResultClicked(docid, position);
-```
+Other functions.
 
-#### Set JSON Web Token (for authentication)
 ```js
-// Add JWT to the search request (if protected search index)
-client.setJWT(token);
-```
+// Next page (call search function to fetch results)
+client.nextPage();
 
-#### Set user token (for personalized search results)
-```js
-// Add a user token to the search request (if personalization in use)
-client.setUserToken('uuid');
+// Previous page
+client.previousPage();
 ```
 
-#### Send personalization events with search query
-In personalized search, user events are typically sent to AddSearch via API and a user token
-is passed with the search query (see setUserToken function). 
-An alternative way is to send user events needed for personalization with the search query.
-
-```js
-// Events depend on the personalization strategy
-// Contact AddSearch for more information
-var events = [
-  {favorite_genre: 'rock'},
-  {favorite_band: 'Red Hot Chili Peppers'},
-  {least_favorite_genre: 'country'}
-];
-
-client.setPersonalizationEvents(events);
-```
+### Filters
 
 #### Define language filter
 ```js
-// Documents in specific language (e.g. "en" or "de")
+// Fetch documents in specific language (e.g. "en" or "de")
 client.setLanguage('en');
 ```
 
@@ -194,34 +174,14 @@ var filter = {
 client.setFilterObject(filter);
 ```
 
-#### Manage paging
-Set page number, page size and sorting parameters. It's possible to order results by:
-- relevance (descending)
-- date (ascending or descending)
-- custom field value (ascending or descending. E.g. *custom_fields.price*)
-```js
-// Defaults: page "1", pageSize "10", sortBy "relevance", sortOrder "desc"
-client.setPaging(page, pageSize, sortBy, sortOrder);
-```
-
-Other functions.
-
-```js
-// Next page (call search function to fetch results)
-client.nextPage();
-
-// Previous page
-client.previousPage();
-```
-
 #### Set result type
 ```js
 // By default, fetch all search results
 // If "organic", Pinned results and Promotions are left out
 client.setResultType('organic');
 ```
 
-#### Facets
+### Facets
 ```js
 // Declare fields for faceting. Number of hits found from
 // these fields will be returned
@@ -234,6 +194,72 @@ Use the following function to get more or less facets.
 client.setNumberOfFacets(20);
 ```
 
+### Search analytics
+#### Send search event to analytics
+When search is executed, send the event to your AddSearch Analytics Dashboard.
+```js
+// If the numberOfResults is 0, the search is shown in the list of "queries with no hits"
+client.sendStatsEvent('search', keyword, {numberOfResults: n});
+```
+
+#### Send click event to analytics
+When a search results is clicked, send the event to your AddSearch Analytics Dashboard. Click information is shown
+in your statistics and used by the self-learning search algorithm.
+```js
+// documentId is the 32-character long id that is part of each hit in search results.
+// position is the position of the document that was clicked, the first result being 1
+client.sendStatsEvent('click', keyword, {documentId: id, position: n});
+```
+
+#### Set or get stats session ID
+Control the search session ID manually. Search queries with the same ID are grouped on the Analytics Dashboard.
+For example, in a search-as-you-type implementation the final keyword of a given session is shown.
+```js
+client.getStatsSessionId();
+client.setStatsSessionId(id);
+```
+
+#### Collect search events automatically
+Send search events automatically to the Analytics Dashboard. Not recommended in search-as-you-type implementations, 
+as every keystroke would fire a statistics event
+```js
+// Control whether search queries are sent to your AddSearch Analytics Dashboard automatically or not (default: true)
+client.setCollectAnalytics(false);
+```
+
+### Personalization
+
+#### Set user token (for personalized search results)
+```js
+// Add a user token to the search request (if personalization in use)
+client.setUserToken('uuid');
+```
+
+#### Send personalization events with search query
+In personalized search, user events are typically sent to AddSearch via API and a user token
+is passed with the search query (see setUserToken function). 
+An alternative way is to send user events needed for personalization with the search query.
+
+```js
+// Events depend on the personalization strategy
+// Contact AddSearch for more information
+var events = [
+  {favorite_genre: 'rock'},
+  {favorite_band: 'Red Hot Chili Peppers'},
+  {least_favorite_genre: 'country'}
+];
+
+client.setPersonalizationEvents(events);
+```
+
+### Other
+
+#### Set JSON Web Token (for authentication)
+```js
+// Add JWT to the search request (if protected search index)
+client.setJWT(token);
+```
+
 ## Supported web browsers and node.js versions
 The client is tested on
 - Chrome
@@ -251,6 +277,12 @@ To modify this client library, clone this repository to your computer and execut
 npm install
 ```
 
+#### Code
+Re-compile automatically when source files are changed
+```sh
+npm run watch
+```
+
 #### Run tests
 ```sh
 npm test

package.json

@@ -41,16 +41,16 @@
   },
   "devDependencies": {
     "@babel/cli": "^7.8.4",
-    "@babel/core": "^7.8.4",
-    "@babel/preset-env": "^7.8.4",
-    "@babel/register": "^7.7.7",
+    "@babel/core": "^7.8.6",
+    "@babel/preset-env": "^7.8.6",
+    "@babel/register": "^7.8.6",
     "babel-loader": "^8.0.6",
     "esm": "^3.2.25",
-    "fetch-mock": "^8.3.2",
-    "mocha": "^6.2.2",
+    "fetch-mock": "^9.0.0",
+    "mocha": "^7.1.0",
     "node-fetch": "^2.6.0",
-    "uglify-js": "^3.7.7",
-    "webpack": "^4.41.5",
-    "webpack-cli": "^3.3.10"
+    "uglify-js": "^3.8.0",
+    "webpack": "^4.42.0",
+    "webpack-cli": "^3.3.11"
   }
 }

src/index.js

@@ -101,19 +101,41 @@ var client = function(sitekey) {
   this.setShuffleAndLimitTo = function(shuffleAndLimitTo) { this.settings.setShuffleAndLimitTo(shuffleAndLimitTo); }
   this.setFuzzyMatch = function(fuzzy) { this.settings.setFuzzyMatch(fuzzy); }
   this.setCollectAnalytics = function(collectAnalytics) { this.settings.setCollectAnalytics(collectAnalytics); }
-  this.searchResultClicked = function(documentId, position) {
-    var data = {
-      action: 'click',
-      session: this.sessionId,
-      keyword: this.settings.getSettings().keyword,
-      docid: documentId,
-      position: position
-    };
-    sendStats(this.sitekey, data);
+  this.setStatsSessionId = function(id) { this.sessionId = id; }
+  this.getStatsSessionId = function() { return this.sessionId; }
+
+  this.sendStatsEvent = function(type, keyword, data) {
+    if (type === 'search') {
+      var data = {
+        action: 'search',
+        session: this.sessionId,
+        keyword: keyword,
+        numberOfResults: data.numberOfResults
+      };
+      sendStats(this.sitekey, data);
+    }
+
+    else if (type === 'click') {
+      var data = {
+        action: 'click',
+        session: this.sessionId,
+        keyword: keyword,
+        docid: data.documentId,
+        position: data.position
+      };
+      sendStats(this.sitekey, data);
+    }
+
+    else {
+      throw "Illegal sendStatsEvent type parameters. Should be search or click)";
+    }
   }
 
+
   // Deprecated
-  this.useFuzzyMatch = function(use) { this.settings.setFuzzyMatch(use); }
+  this.searchResultClicked = function(documentId, position) {
+    this.sendStatsEvent('click', this.settings.getSettings().keyword, {documentId: documentId, position: position});
+  }
 }
 
 module.exports = client;