wingbot 3.45.2 → 3.46.0-alpha.10

package/index.js

@@ -52,7 +52,11 @@ const {
     bufferloader,
     MemoryStateStorage
 } = require('./src/tools');
-const flags = require('./src/flags');
+const {
+    TrackingCategory,
+    TrackingType,
+    ResponseFlag
+} = require('./src/analytics/consts');
 
 const { version: wingbotVersion } = require('./package.json');
 
@@ -122,8 +126,10 @@ module.exports = {
     // tests
     ConversationTester,
 
-    // flags
-    ...flags,
+    // flags & tracking
+    TrackingCategory,
+    TrackingType,
+    ResponseFlag,
 
     wingbotVersion,
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wingbot",
-  "version": "3.45.2",
+  "version": "3.46.0-alpha.10",
   "description": "Enterprise Messaging Bot Conversation Engine",
   "main": "index.js",
   "scripts": {
@@ -9,7 +9,7 @@
     "doc": "npm run doc:gql && node ./bin/makeApiDoc.js && cpy ./CHANGELOG.md ./doc && gitbook install ./doc && gitbook build ./doc && rimraf -rf ./docs && rimraf --rf ./doc/CHANGELOG.md && move-cli ./doc/_book ./docs",
     "test": "npm run test:lint && npm run test:coverage && npm run test:coverage:threshold",
     "test:coverage": "nyc --reporter=html mocha ./test && nyc report",
-    "test:coverage:threshold": "nyc check-coverage --lines 90 --functions 90 --branches 80",
+    "test:coverage:threshold": "nyc check-coverage --lines 90 --functions 89 --branches 80",
     "test:backend": "mocha ./test",
     "test:lint": "eslint --ext .js src test *.js plugins"
   },

package/src/BotApp.js

@@ -116,6 +116,8 @@ class BotApp {
         this._senderLogger = chatLogStorage;
         this._verify = promisify(jwt.verify);
 
+        this._bot = bot;
+
         this._processor = new Processor(bot, {
             ...processorOptions,
             secret,
@@ -202,9 +204,14 @@ class BotApp {
             analyticsStorage.setDefaultLogger(log);
         }
 
+        // @ts-ignore
+        const { snapshot = null, botId = null } = this._bot;
+
         const { onInteraction, onEvent } = onInteractionHandler({
             log,
             anonymize: this._textFilter,
+            snapshot,
+            botId,
             ...options
         }, analyticsStorage);
 

package/src/BuildRouter.js

@@ -39,6 +39,7 @@ const MESSAGE_RESOLVER_NAME = 'botbuild.message';
  * @typedef {object} Route
  * @prop {number} id
  * @prop {string|null} path
+ * @prop {string|null} [skill]
  * @prop {Resolver[]} resolvers
  * @prop {boolean} [isFallback]
  * @prop {string[]} [aiTags]
@@ -238,6 +239,14 @@ class BuildRouter extends Router {
         }
     }
 
+    get snapshot () {
+        return this._snapshot;
+    }
+
+    get botId () {
+        return this._botId;
+    }
+
     /**
      * @returns {C}
      */
@@ -674,9 +683,10 @@ class BuildRouter extends Router {
      *
      * @param {TransformedRoute} route
      * @param {boolean} nextRouteIsSameResponder
+     * @param {string} includedBlockId
      * @returns {Middleware<S,C>[]}
      */
-    _buildRouteHead (route, nextRouteIsSameResponder) {
+    _buildRouteHead (route, nextRouteIsSameResponder, includedBlockId) {
         const resolvers = [];
 
         if (!route.isFallback) {
@@ -712,6 +722,11 @@ class BuildRouter extends Router {
                 if (bounceResolver) {
                     resolvers.push(bounceResolver);
                 }
+            } else if (!includedBlockId && route.skill) {
+                resolvers.push((req, res) => {
+                    res.trackAsSkill(route.skill);
+                    return Router.CONTINUE;
+                });
             }
         }
 
@@ -752,7 +767,7 @@ class BuildRouter extends Router {
             };
 
             const resolvers = [
-                ...this._buildRouteHead(route, nextRouteIsSameResponder),
+                ...this._buildRouteHead(route, nextRouteIsSameResponder, includedBlockId),
                 ...this.buildResolvers(route.resolvers, route, buildInfo)
             ];
 

package/src/Processor.js

@@ -16,6 +16,9 @@ const { mergeState, isUserInteraction } = require('./utils/stateVariables');
 /** @typedef {import('./ReducerWrapper')} ReducerWrapper */
 /** @typedef {import('./Router')} Router */
 /** @typedef {import('./BuildRouter')} BuildRouter */
+/** @typedef {import('./analytics/consts').TrackingCategory} TrackingCategory */
+/** @typedef {import('./analytics/consts').TrackingType} TrackingType */
+/** @typedef {import('./analytics/consts').ResponseFlag} ResponseFlag */
 
 /**
  * @typedef {object} AutoTypingConfig
@@ -35,8 +38,8 @@ const { mergeState, isUserInteraction } = require('./utils/stateVariables');
 
 /**
  * @typedef {object} TrackingEvent
- * @prop {string} type
- * @prop {string} category
+ * @prop {TrackingType} type
+ * @prop {TrackingCategory} category
  * @prop {string} action
  * @prop {string} label
  * @prop {number} value
@@ -55,7 +58,10 @@ const { mergeState, isUserInteraction } = require('./utils/stateVariables');
  * @prop {object} state
  * @prop {object} data
  * @prop {string|null} skill
- * @prop {TrackingObject} tracking
+ * @prop {TrackingObject} tracking - deprecated
+ * @prop {TrackingEvent[]} events
+ * @prop {ResponseFlag|null} flag
+ * @prop {boolean} nonInteractive
  */
 
 /**
@@ -134,6 +140,19 @@ function NAME_FROM_STATE (state) {
 }
 
 const MAX_TS = 9999999999999;
+const CHARS = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
+
+function toBase (number) {
+    let result = '';
+    let integer = number;
+
+    do {
+        result = CHARS[integer % 62] + result;
+        integer = Math.floor(integer / 62);
+    } while (integer > 0);
+
+    return result;
+}
 
 /**
  * Messaging event processor
@@ -381,7 +400,7 @@ class Processor extends EventEmitter {
             } = await this
                 ._processMessage(message, pageId, messageSender, responderData, preloadPromise));
 
-            await this._emitInteractionEvent(req, messageSender, state, data);
+            await this._emitInteractionEvent(req, res, messageSender, state, data);
 
             return messageSender.finished(req, res, null, errorHandler);
         } catch (e) {
@@ -394,12 +413,13 @@ class Processor extends EventEmitter {
     /**
      *
      * @param {Request} req
+     * @param {Responder} res
      * @param {ReturnSender} messageSender
      * @param {object} state
      * @param {object} data
      * @returns {Promise}
      */
-    _emitInteractionEvent (req, messageSender, state, data) {
+    _emitInteractionEvent (req, res, messageSender, state, data) {
         const shouldNotTrack = data._initialEventShouldNotBeTracked === true;
 
         if (shouldNotTrack) {
@@ -408,7 +428,10 @@ class Processor extends EventEmitter {
 
         const { _lastAction: lastAction = null } = req.state;
         const actions = messageSender.visitedInteractions;
-        const skill = state._trackAsSkill || null;
+        const skill = typeof res.newState._trackAsSkill === 'undefined'
+            ? (req.state._trackAsSkill || null)
+            : res.newState._trackAsSkill;
+        const { events = [] } = messageSender.tracking;
 
         const event = {
             req,
@@ -417,7 +440,10 @@ class Processor extends EventEmitter {
             state,
             data,
             skill,
-            tracking: messageSender.tracking
+            tracking: messageSender.tracking,
+            events,
+            flag: res.senderMeta.flag,
+            nonInteractive: !isUserInteraction(req)
         };
 
         return Promise.allSettled([
@@ -575,27 +601,35 @@ class Processor extends EventEmitter {
                 let {
                     _sct: sessionCount = 0,
                     _sid: sessionId = null,
-                    _segStamp: ts = 0,
+                    _sst: sessionStart = 0,
+                    _sts: sessionTs = (state._segStamp || 0),
                     _snew: sessionCreated
                 } = state;
 
+                const interactive = isUserInteraction(req);
+
                 if ((isUserInteraction(req)
-                    && (ts + this.options.sessionDuration) < Date.now())
+                    && (sessionTs + this.options.sessionDuration) < Date.now())
                         || !sessionId) {
 
+                    sessionStart = timestamp;
+                    sessionTs = timestamp;
                     sessionId = Processor._createSessionId(req.pageId, req.senderId, timestamp);
                     sessionCount++;
                     sessionCreated = true;
                 } else {
                     sessionCreated = false;
-                }
 
-                ts = timestamp;
+                    if (interactive) {
+                        sessionTs = timestamp;
+                    }
+                }
 
                 Object.assign(state, {
                     _sct: sessionCount,
                     _sid: sessionId,
-                    _segStamp: ts,
+                    _sst: sessionStart,
+                    _sts: sessionTs,
                     _snew: sessionCreated
                 });
             } else {
@@ -785,21 +819,18 @@ class Processor extends EventEmitter {
             .digest('hex');
 
         return senderHash.match(/[a-f0-9]{1,13}/g)
-            .map((v) => parseInt(v, 16).toString(36))
+            .map((v) => toBase(parseInt(v, 16)))
             .join('');
     }
 
     static _createSessionId (pageId, senderId, timestamp = Date.now()) {
-        const senderShort = Processor._shakeShort(`${senderId}|${pageId}}`, 9);
+        const senderShort = Processor._shakeShort(`${senderId}|${pageId}}`, 12);
 
-        const rand = Math.floor(Math.random() * Number.MAX_SAFE_INTEGER)
-            .toString(36);
+        const rand = toBase(Math.floor(Math.random() * Number.MAX_SAFE_INTEGER));
 
-        const randTS = Math.floor(Date.now() % 1000)
-            .toString(36);
+        const randTS = toBase(Math.floor(Date.now() % 10000));
 
-        const ts = Math.floor(MAX_TS - timestamp)
-            .toString(36);
+        const ts = toBase(Math.floor(MAX_TS - timestamp));
 
         // console.log({
         //     base: `${ts}.${senderShort}`.length,
@@ -811,7 +842,7 @@ class Processor extends EventEmitter {
         // });
 
         return `${ts}.${senderShort}`
-            .padEnd(26, randTS)
+            .padEnd(28, randTS)
             .padEnd(32, rand);
     }
 

package/src/Request.js

@@ -6,7 +6,7 @@
 const Ai = require('./Ai');
 const { tokenize, parseActionPayload } = require('./utils');
 const { quickReplyAction } = require('./utils/quickReplies');
-const { FLAG_DISAMBIGUATION_SELECTED } = require('./flags');
+const { ResponseFlag } = require('./analytics/consts');
 const { getSetState } = require('./utils/getUpdate');
 const { vars, checkSetState } = require('./utils/stateVariables');
 const OrchestratorClient = require('./OrchestratorClient');
@@ -391,7 +391,7 @@ class Request {
                     data: {
                         ...data,
                         _senderMeta: {
-                            flag: FLAG_DISAMBIGUATION_SELECTED,
+                            flag: ResponseFlag.DISAMBIGUATION_SELECTED,
                             likelyIntent: intent.intent,
                             disambText: text
                         }
@@ -801,6 +801,7 @@ class Request {
      * @returns {Action|null}
      */
     expected () {
+        // @ts-ignore
         return this.state._expected || null;
     }
 
@@ -816,6 +817,7 @@ class Request {
      */
     expectedKeywords (justOnce = false) {
         const {
+            // @ts-ignore
             _expectedKeywords: exKeywords
         } = this.state;
 
@@ -855,7 +857,9 @@ class Request {
      */
     expectedContext (justOnce = false, includeKeywords = false) {
         const ad = this.actionData();
+        // @ts-ignore
         const expected = ad._useExpected || this.state._expected;
+        // @ts-ignore
         const confident = this.state._expectedConfidentInput;
 
         const ret = {};
@@ -1097,6 +1101,7 @@ class Request {
      * @returns {boolean}
      */
     isConfidentInput () {
+        // @ts-ignore
         return this.state._expectedConfidentInput === true;
     }
 
@@ -1123,11 +1128,15 @@ class Request {
             res = parseActionPayload(this.message.quick_reply);
         }
 
+        // @ts-ignore
         if (!res && this.state._expectedKeywords) {
+            // @ts-ignore
             res = this._actionByExpectedKeywords(this.state._expected);
         }
 
+        // @ts-ignore
         if (!res && this.state._expected) {
+            // @ts-ignore
             res = parseActionPayload(this.state._expected);
         }
 
@@ -1215,7 +1224,9 @@ class Request {
     }
 
     _getLocalPathRegexp () {
+        // @ts-ignore
         if (this.state._lastVisitedPath) {
+            // @ts-ignore
             return new RegExp(`^${this.state._lastVisitedPath}/[^/]+`);
         }
         let expected = this.expected();
@@ -1295,6 +1306,7 @@ class Request {
     }
 
     _actionByExpectedKeywords (expected) {
+        // @ts-ignore
         if (!this.state._expectedKeywords) {
             return null;
         }
@@ -1315,8 +1327,10 @@ class Request {
 
     _resolveQuickReplyActions () {
         if (this._quickReplyActions === null) {
+            // @ts-ignore
             if (this.state._expectedKeywords) {
                 this._quickReplyActions = quickReplyAction(
+                    // @ts-ignore
                     this.state._expectedKeywords,
                     this,
                     Ai.ai
@@ -1377,6 +1391,7 @@ class Request {
      */
     expectedEntities () {
         const {
+            // @ts-ignore
             _expectedKeywords: exKeywords
         } = this.state;
 

package/src/Responder.js

@@ -9,7 +9,7 @@ const ButtonTemplate = require('./templates/ButtonTemplate');
 const GenericTemplate = require('./templates/GenericTemplate');
 const ListTemplate = require('./templates/ListTemplate');
 const { makeAbsolute, makeQuickReplies } = require('./utils');
-const { FLAG_DISAMBIGUATION_OFFERED, FLAG_DO_NOT_LOG } = require('./flags');
+const { ResponseFlag } = require('./analytics/consts');
 const { checkSetState } = require('./utils/stateVariables');
 const {
     FEATURE_VOICE,
@@ -23,6 +23,9 @@ const TYPE_MESSAGE_TAG = 'MESSAGE_TAG';
 const EXCEPTION_HOPCOUNT_THRESHOLD = 5;
 
 /** @typedef {import('./Request')} Request */
+/** @typedef {import('./ReturnSender').UploadResult} UploadResult */
+/** @typedef {import('./analytics/consts').TrackingCategory} TrackingCategory */
+/** @typedef {import('./analytics/consts').TrackingType} TrackingType */
 
 /**
  * @enum {string} ExpectedInput
@@ -48,7 +51,7 @@ Object.freeze(ExpectedInput);
 
 /**
  * @typedef {object} SenderMeta
- * @prop {string|null} flag
+ * @prop {ResponseFlag|null} flag
  * @prop {string} [likelyIntent]
  * @prop {string} [disambText]
  * @prop {string[]} [disambiguationIntents]
@@ -71,8 +74,6 @@ Object.freeze(ExpectedInput);
  * @returns {VoiceControl}
  */
 
-/** @typedef {import('./ReturnSender').UploadResult} UploadResult */
-
 /**
  * Instance of responder is passed as second parameter of handler (res)
  *
@@ -200,7 +201,7 @@ class Responder {
      * @returns {this}
      */
     doNotLogTheEvent () {
-        this._senderMeta = { flag: FLAG_DO_NOT_LOG };
+        this._senderMeta = { flag: ResponseFlag.DO_NOT_LOG };
         return this;
     }
 
@@ -209,8 +210,8 @@ class Responder {
      * Events are aggregated within ReturnSender and can be caught
      * within Processor's `interaction` event (event.tracking.events)
      *
-     * @param {string} type - (log,report,conversation,audit,user)
-     * @param {string} category
+     * @param {TrackingType} type - (log,report,conversation,audit,user,training)
+     * @param {TrackingCategory} category
      * @param {string} [action]
      * @param {string} [label]
      * @param {number} [value]
@@ -471,7 +472,7 @@ class Responder {
 
             if (disambiguationIntents.length > 0) {
                 this._senderMeta = {
-                    flag: FLAG_DISAMBIGUATION_OFFERED,
+                    flag: ResponseFlag.DISAMBIGUATION_OFFERED,
                     disambiguationIntents
                 };
             }
@@ -1015,6 +1016,8 @@ class Responder {
             $hopCount++;
         }
 
+        this._senderMeta = { flag: ResponseFlag.HANDOVER };
+
         if (data === null) {
             metadata = JSON.stringify({
                 data: { $hopCount }

package/src/ReturnSender.js

@@ -5,10 +5,11 @@
 
 const ai = require('./Ai');
 const { FEATURE_PHRASES, FEATURE_TRACKING } = require('./features');
-const { FLAG_DO_NOT_LOG } = require('./flags');
+const { ResponseFlag } = require('./analytics/consts');
 
 /** @typedef {import('./Request')} Request */
 /** @typedef {import('./Responder')} Responder */
+/** @typedef {import('./Processor').TrackingObject} TrackingObject */
 
 /**
  * @typedef {object} ChatLogStorage
@@ -155,6 +156,9 @@ class ReturnSender {
         });
     }
 
+    /**
+     * @returns {TrackingObject}
+     */
     get tracking () {
         return this._tracking;
     }
@@ -531,7 +535,7 @@ class ReturnSender {
                 };
             }
 
-            if (!this._logger || meta.flag === FLAG_DO_NOT_LOG) {
+            if (!this._logger || meta.flag === ResponseFlag.DO_NOT_LOG) {
                 // noop
             } else if (error) {
                 await Promise.resolve(this._logger

package/src/analytics/consts.js

@@ -0,0 +1,110 @@
+/**
+ * @author David Menger
+ */
+'use strict';
+
+/**
+ * @enum {string}
+ */
+const ResponseFlag = {
+    /**
+     * Disambiguation quick reply was selected
+     */
+    DISAMBIGUATION_SELECTED: 'd',
+
+    /**
+     * Disambiguation occured - user was asked to choose the right meaning
+     */
+    DISAMBIGUATION_OFFERED: 'o',
+
+    /**
+     * Do not log the event
+     */
+    DO_NOT_LOG: '!',
+
+    /**
+     * Handover occurred
+     */
+    HANDOVER: 'h'
+};
+
+/**
+ * @enum {string}
+ */
+const TrackingType = { // max length 12
+    CONVERSATION_EVENT: 'conversation',
+    TRAINING: 'train',
+    PAGE_VIEW: 'page_view',
+    REPORT: 'report'
+};
+
+/**
+ * @enum {string} TrackingCategory
+ */
+const TrackingCategory = { // max length 3
+    // PAGE_VIEW: 'page_view'
+    PAGE_VIEW_FIRST: 'pf',
+    PAGE_VIEW_SUBSEQUENT: 'pp',
+
+    // CONVERSATION_EVENT: 'conversation'
+    STICKER: 'sti',
+    IMAGE: 'img',
+    LOCATION: 'loc',
+    ATTACHMENT: 'att',
+    TEXT: 'txt',
+    QUICK_REPLY: 'qr',
+    OPT_IN: 'oin',
+    REFERRAL: 'ref',
+    POSTBACK_BUTTON: 'btn',
+    URL_LINK: 'url',
+    OTHER: 'oth',
+    HANDOVER_TO_BOT: 'bot',
+
+    // TRAINING: 'train'
+    INTENT_DETECTION: 'int',
+    DISAMBIGUATION_SELECTED: 'dis',
+    DISAMBIGUATION_OFFERED: 'dio',
+
+    // REPORT: 'report'
+    REPORT_FEEDBACK: 'fdb',
+    HANDOVER_OCCURRED: 'hum'
+};
+
+/**
+ * @type {Object<TrackingCategory,string>}
+ */
+const CATEGORY_LABELS = {
+    // PAGE_VIEW: 'page_view'
+    [TrackingCategory.PAGE_VIEW_FIRST]: 'Bot: Interaction',
+    [TrackingCategory.PAGE_VIEW_SUBSEQUENT]: 'Bot: Sub-interaction',
+
+    // CONVERSATION_EVENT: 'conversation'
+    [TrackingCategory.STICKER]: 'User: Sticker',
+    [TrackingCategory.IMAGE]: 'User: Image',
+    [TrackingCategory.LOCATION]: 'User: Location',
+    [TrackingCategory.ATTACHMENT]: 'User: Attachement', // yes, with typo
+    [TrackingCategory.TEXT]: 'User: Text',
+    [TrackingCategory.QUICK_REPLY]: 'User: Quick reply',
+    [TrackingCategory.OPT_IN]: 'Entry: Optin',
+    [TrackingCategory.REFERRAL]: 'Entry: Referral',
+    [TrackingCategory.POSTBACK_BUTTON]: 'User: Button - bot',
+    [TrackingCategory.URL_LINK]: 'User: Button - url',
+    [TrackingCategory.OTHER]: 'User: Other',
+    [TrackingCategory.HANDOVER_TO_BOT]: 'Entry: Handover in',
+
+    // TRAINING: 'train'
+    [TrackingCategory.INTENT_DETECTION]: 'Intent: Detection',
+    [TrackingCategory.DISAMBIGUATION_SELECTED]: 'Disambiguation: selected',
+    [TrackingCategory.DISAMBIGUATION_OFFERED]: 'Disambiguation: offered',
+
+    // REPORT: 'report'
+    [TrackingCategory.REPORT_FEEDBACK]: 'User: Feedback',
+    [TrackingCategory.HANDOVER_OCCURRED]: 'Bot: Handover out'
+};
+
+module.exports = {
+    CATEGORY_LABELS,
+    TrackingType,
+    TrackingCategory,
+    ResponseFlag
+};

package/src/analytics/onInteractionHandler.js

@@ -3,8 +3,11 @@
  */
 'use strict';
 
-const { replaceDiacritics } = require('webalize');
+const { replaceDiacritics, webalize } = require('webalize');
 const Ai = require('../Ai');
+const {
+    TrackingType, TrackingCategory, CATEGORY_LABELS, ResponseFlag
+} = require('./consts');
 
 /** @typedef {import('../Processor').InteractionEvent} InteractionEvent */
 /** @typedef {import('../Processor').IInteractionHandler} IInteractionHandler */
@@ -23,11 +26,61 @@ const Ai = require('../Ai');
 
 /**
  * @typedef {object} Event
- * @prop {'conversation'|'page_view'|string} type
- * @prop {string} [category]
+ * @prop {TrackingType} type
+ * @prop {TrackingCategory} [category]
  * @prop {string} [action]
  * @prop {string} [label]
  * @prop {number} [value]
+ * @prop {string} [lang]
+ */
+
+/**
+ * @typedef {object} ConversationEventExtension
+ * @prop {string} [lastAction]
+ * @prop {string} [skill]
+ * @prop {string} [text]
+ * @prop {string} [expected]
+ * @prop {boolean} expectedTaken
+ * @prop {boolean} isContextUpdate
+ * @prop {boolean} isAttachment
+ * @prop {boolean} isNotification
+ * @prop {boolean} isQuickReply
+ * @prop {boolean} isPassThread
+ * @prop {boolean} isPostback
+ * @prop {boolean} isText
+ * @prop {boolean} didHandover
+ * @prop {boolean} withUser
+ * @prop {string} [userId]
+ * @prop {number} [feedback]
+ * @prop {string} [winnerAction]
+ * @prop {string} [winnerIntent]
+ * @prop {string[]|string} [winnerEntities]
+ * @prop {number} [winnerScore]
+ * @prop {boolean} [winnerTaken]
+ * @prop {string} [intent]
+ * @prop {number} [intentScore]
+ * @prop {string[]|string} [entities]
+ * @prop {string[]|string} allActions
+ * @prop {boolean} nonInteractive
+ *
+ * @typedef {Event & ConversationEventExtension} ConversationEvent
+ */
+
+/**
+ * @typedef {object} PageViewEventExtension
+ * @prop {string} [lastAction]
+ * @prop {string} [prevAction]
+ * @prop {string} [skill]
+ * @prop {string[]|string} allActions
+ * @prop {boolean} nonInteractive
+ * @prop {boolean} isGoto
+ * @prop {boolean} withUser
+ *
+ * @typedef {Event & PageViewEventExtension} PageViewEvent
+ */
+
+/**
+ * @typedef {ConversationEvent | Event | PageViewEvent} TrackingEvent
  */
 
 /**
@@ -35,6 +88,13 @@ const Ai = require('../Ai');
  * @prop {number} [sessionCount]
  * @prop {string} [lang]
  * @prop {string} [action]
+ * @prop {string} [snapshot]
+ * @prop {string} [botId]
+ * @prop {boolean} [didHandover]
+ * @prop {number|null} [feedback]
+ * @prop {string} [timeZone]
+ * @prop {number} [sessionStart]
+ * @prop {number} [sessionDuration]
  */
 
 /**
@@ -53,11 +113,12 @@ const Ai = require('../Ai');
  * @param {string} pageId
  * @param {string} senderId
  * @param {string} sessionId
- * @param {Event[]} events
+ * @param {TrackingEvent[]} events
  * @param {GAUser} [user]
  * @param {number} [ts]
  * @param {boolean} [nonInteractive]
  * @param {boolean} [sessionStarted]
+ * @param {SessionMetadata} [metadata]
  * @returns {Promise}
  */
 
@@ -72,6 +133,10 @@ const Ai = require('../Ai');
  * @prop {StoreEvents} storeEvents
  * @prop {CreateUserSession} createUserSession
  * @prop {boolean} [hasExtendedEvents]
+ * @prop {boolean} [supportsArrays]
+ * @prop {boolean} [useDescriptiveCategories]
+ * @prop {boolean} [useExtendedScalars]
+ * @prop {boolean} [parallelSessionInsert]
  */
 
 /**
@@ -88,7 +153,7 @@ const Ai = require('../Ai');
 
 /**
  * @typedef {object} TrackingEvents
- * @prop {Event[]} events
+ * @prop {TrackingEvent[]} events
  */
 
 /**
@@ -98,6 +163,9 @@ const Ai = require('../Ai');
 
 /**
  * @typedef {object} HandlerConfig
+ * @prop {string} [snapshot]
+ * @prop {string} [botId]
+ * @prop {string} [timeZone] - default UTC
  * @prop {boolean} [enabled] - default true
  * @prop {boolean} [throwException] - default false
  * @prop {IGALogger} [log] - console like logger
@@ -134,12 +202,27 @@ function onInteractionHandler (
         enabled = true,
         throwException = false,
         log = console,
+        snapshot,
+        botId,
+        timeZone = 'UTC',
         anonymize = (x) => x,
         userExtractor = (state) => null // eslint-disable-line no-unused-vars
     },
     analyticsStorage,
     ai = Ai.ai
 ) {
+    const {
+        supportsArrays = false,
+        useExtendedScalars = false,
+        hasExtendedEvents = false,
+        useDescriptiveCategories = true,
+        parallelSessionInsert = false
+    } = analyticsStorage;
+
+    const asArray = (data = []) => (supportsArrays ? data : data.join(','));
+    const asCategory = (cat) => (useDescriptiveCategories && CATEGORY_LABELS[cat]) || cat;
+    const noneAction = useExtendedScalars ? null : '(none)';
+    const noneValue = useExtendedScalars ? null : 0;
 
     /**
      * @param {InteractionEvent} params
@@ -151,13 +234,14 @@ function onInteractionHandler (
         // state,
         // data,
         skill,
-        tracking
+        events,
+        flag,
+        nonInteractive
     }) {
         if (!enabled) {
             return;
         }
         try {
-            const nonInteractive = !!req.campaign;
             const {
                 pageId,
                 senderId,
@@ -168,19 +252,52 @@ function onInteractionHandler (
                 _snew: createSession,
                 _sct: sessionCount,
                 _sid: sessionId,
+                _sst: sessionStart,
+                _sts: sessionTs,
                 lang
             } = req.state;
 
-            const [action = '(none)', ...otherActions] = actions;
+            const trackEvents = [];
+
+            const [action = noneAction, ...otherActions] = actions;
+
+            const feedbackEvent = events.find((e) => e.type === TrackingType.REPORT
+                && e.category === TrackingCategory.REPORT_FEEDBACK);
+            const feedback = feedbackEvent
+                ? feedbackEvent.value
+                : noneValue;
+            let didHandover = flag === ResponseFlag.HANDOVER;
+            const hasHandoverEvent = events
+                .some((e) => e.category === TrackingCategory.HANDOVER_OCCURRED);
+
+            if (didHandover && !hasHandoverEvent) {
+                trackEvents.push({
+                    type: TrackingType.REPORT,
+                    category: asCategory(TrackingCategory.HANDOVER_OCCURRED),
+                    action: null,
+                    label: null,
+                    value: noneValue
+                });
+            } else if (hasHandoverEvent) {
+                didHandover = true;
+            }
 
-            if (createSession) {
-                const metadata = {
-                    sessionCount,
-                    lang,
-                    action
-                };
+            const metadata = {
+                sessionCount,
+                lang,
+                action,
+                snapshot,
+                botId,
+                didHandover,
+                feedback,
+                timeZone,
+                sessionStart,
+                sessionDuration: sessionTs - sessionStart
+            };
 
-                await analyticsStorage.createUserSession(
+            let sessionPromise;
+            if (createSession) {
+                sessionPromise = analyticsStorage.createUserSession(
                     pageId,
                     senderId,
                     sessionId,
@@ -188,6 +305,11 @@ function onInteractionHandler (
                     timestamp,
                     nonInteractive
                 );
+
+                if (!parallelSessionInsert) {
+                    await sessionPromise;
+                    sessionPromise = null;
+                }
             }
 
             const [{
@@ -200,6 +322,7 @@ function onInteractionHandler (
                 : anonymize(
                     replaceDiacritics(req.text()).replace(/\s+/g, ' ').toLowerCase().trim()
                 );
+            const useSkill = (skill && webalize(skill)) || noneAction;
 
             let winnerAction = '';
             let winnerScore = 0;
@@ -211,7 +334,7 @@ function onInteractionHandler (
 
             if (winners.length > 0) {
                 [{
-                    action: winnerAction = '(none)',
+                    action: winnerAction = noneAction,
                     sort: winnerScore = 0,
                     intent: { intent: winnerIntent, entities: winnerEntities = [] }
                 }] = winners;
@@ -220,6 +343,7 @@ function onInteractionHandler (
             }
 
             const expected = req.expected() ? req.expected().action : '';
+            const user = userExtractor(req.state);
 
             const isContextUpdate = req.isSetContext();
             const isNotification = !!req.campaign;
@@ -229,13 +353,17 @@ function onInteractionHandler (
             const isText = !isQuickReply && req.isText();
             const isPostback = req.isPostBack();
 
-            const allActions = actions.join(',');
+            const allActions = asArray(actions);
             const requestAction = req.action();
 
-            const events = [];
+            const langsExtension = hasExtendedEvents
+                ? { lang }
+                : { cd1: lang };
+
+            const withUser = user !== null && !!user.id;
 
             const actionMeta = {
-                requestAction: req.action() || '(none)',
+                requestAction: req.action() || noneAction,
                 expected,
                 expectedTaken: requestAction === expected,
                 isContextUpdate,
@@ -245,47 +373,59 @@ function onInteractionHandler (
                 isPassThread,
                 isText,
                 isPostback,
+                didHandover,
+                withUser,
+                feedback,
+                skill: useSkill,
                 winnerAction,
                 winnerIntent,
-                winnerEntities: winnerEntities.map((e) => e.entity).join(','),
+                winnerEntities: asArray(winnerEntities.map((e) => e.entity)),
                 winnerScore,
                 winnerTaken,
                 intent,
                 intentScore: score,
-                entities: req.entities.map((e) => e.entity).join(','),
+                entities: asArray(req.entities.map((e) => e.entity)),
                 text,
                 allActions
             };
 
-            events.push({
-                type: 'page_view',
+            const notHandled = actions.some((a) => a.match(/\*$/)) && !req.isQuickReply();
+            const value = notHandled ? 1 : 0;
+
+            trackEvents.push({
+                type: TrackingType.PAGE_VIEW,
+                category: asCategory(TrackingCategory.PAGE_VIEW_FIRST),
                 action,
+                label: (isText || isQuickReply ? text : null),
+                value,
                 allActions,
                 nonInteractive,
                 lastAction,
+                // @ts-ignore
                 prevAction: lastAction,
-                skill,
-                lang,
-                cd1: req.state.lang,
-                ...(analyticsStorage.hasExtendedEvents ? {} : actionMeta)
+                skill: useSkill,
+                isGoto: false,
+                withUser,
+                ...langsExtension,
+                ...(hasExtendedEvents ? {} : actionMeta)
             });
 
             let prevAction = action;
 
-            events.push(
+            trackEvents.push(
                 ...otherActions.map((a) => {
                     const r = {
-                        type: 'page_view',
+                        type: TrackingType.PAGE_VIEW,
+                        category: asCategory(TrackingCategory.PAGE_VIEW_SUBSEQUENT),
                         action: a,
+                        value: 0,
                         allActions,
                         nonInteractive: false,
                         lastAction,
                         prevAction,
-                        skill,
+                        skill: useSkill,
                         isGoto: true,
-                        ...(analyticsStorage.hasExtendedEvents
-                            ? { lang }
-                            : { cd1: lang })
+                        ...langsExtension
                     };
 
                     prevAction = a;
@@ -293,104 +433,98 @@ function onInteractionHandler (
                 })
             );
 
-            events.push(
-                ...tracking.events.map(({
-                    type, category, action: eventAction, label, value
+            trackEvents.push(
+                ...events.map(({
+                    type, category, action: eventAction, label, value: eVal
                 }) => ({
                     lastAction,
                     type,
-                    category,
+                    category: asCategory(category),
                     action: eventAction,
                     label,
-                    value,
-                    ...(analyticsStorage.hasExtendedEvents
-                        ? { lang }
-                        : { cd1: lang })
+                    value: eVal,
+                    ...langsExtension
                 }))
             );
 
             if (!nonInteractive) {
 
                 if (req.isText()) {
-                    events.push({
-                        type: 'ai',
+                    trackEvents.push({
+                        type: TrackingType.TRAINING,
                         // @ts-ignore
                         lastAction,
-                        category: 'Intent: Detection',
+                        category: asCategory(TrackingCategory.INTENT_DETECTION),
                         intent,
                         action,
                         label: text,
                         value: score >= ai.confidence ? 0 : 1,
-                        ...(analyticsStorage.hasExtendedEvents
-                            ? { lang }
-                            : { cd1: lang })
+                        ...langsExtension
                     });
                 }
 
-                const notHandled = actions.some((a) => a.match(/\*$/)) && !req.isQuickReply();
-
-                let actionCategory = 'User: ';
-                let label = '(none)';
-                const value = notHandled ? 1 : 0;
+                let actionCategory;
+                let label = noneAction;
 
-                if (req.isSticker()) {
-                    actionCategory += 'Sticker';
+                if (isPassThread) {
+                    actionCategory = TrackingCategory.HANDOVER_TO_BOT;
+                } else if (req.isSticker()) {
+                    actionCategory = TrackingCategory.STICKER;
                     label = req.attachmentUrl(0);
                 } else if (req.isImage()) {
-                    actionCategory += 'Image';
+                    actionCategory = TrackingCategory.IMAGE;
                     label = req.attachmentUrl(0);
                 } else if (req.hasLocation()) {
-                    actionCategory += 'Location';
+                    actionCategory = TrackingCategory.LOCATION;
                     const { lat, long } = req.getLocation();
                     label = `${lat}, ${long}`;
                 } else if (isAttachment) {
-                    actionCategory += 'Attachement';
+                    actionCategory = TrackingCategory.ATTACHMENT;
                     label = req.attachment(0).type;
                 } else if (isText) {
-                    actionCategory += 'Text';
+                    actionCategory = TrackingCategory.TEXT;
                     label = text;
                 } else if (isQuickReply) {
-                    actionCategory += 'Quick reply';
+                    actionCategory = TrackingCategory.QUICK_REPLY;
                     label = text;
-                } else if (req.isReferral() || req.isOptin()) {
-                    actionCategory = req.isOptin()
-                        ? 'Entry: Optin'
-                        : 'Entry: Referral';
+                } else if (req.isOptin()) {
+                    actionCategory = TrackingCategory.OPT_IN;
+                } else if (req.isReferral()) {
+                    actionCategory = TrackingCategory.REFERRAL;
                 } else if (isPostback) {
-                    actionCategory += 'Button - bot';
-                    label = req.data.postback.title || '(unknown)';
+                    actionCategory = TrackingCategory.POSTBACK_BUTTON;
+                    label = req.event.postback.title || (useExtendedScalars ? null : '(unknown)');
                 } else {
-                    actionCategory += 'Other';
+                    actionCategory = TrackingCategory.OTHER;
                 }
 
-                events.push({
+                trackEvents.push({
                     ...(analyticsStorage.hasExtendedEvents ? actionMeta : {}),
-                    type: 'conversation',
-                    // @ts-ignore
+                    type: TrackingType.CONVERSATION_EVENT,
                     lastAction,
-                    category: actionCategory,
+                    category: asCategory(actionCategory),
                     action,
                     label,
                     value,
-                    ...(analyticsStorage.hasExtendedEvents
-                        ? { lang }
-                        : { cd1: lang })
+                    ...langsExtension
                 });
             }
 
-            const user = userExtractor(req.state);
-
-            await analyticsStorage.storeEvents(
-                pageId,
-                senderId,
-                sessionId,
-                // @ts-ignore
-                events,
-                user,
-                timestamp,
-                nonInteractive,
-                createSession
-            );
+            await Promise.all([
+                analyticsStorage.storeEvents(
+                    pageId,
+                    senderId,
+                    sessionId,
+                    // @ts-ignore
+                    trackEvents,
+                    user,
+                    timestamp,
+                    nonInteractive,
+                    createSession,
+                    metadata
+                ),
+                sessionPromise
+            ]);
         } catch (e) {
             if (throwException) {
                 throw e;
@@ -432,7 +566,7 @@ function onInteractionHandler (
                 [{
                     // @ts-ignore
                     lastAction,
-                    ...(analyticsStorage.hasExtendedEvents
+                    ...(hasExtendedEvents
                         ? { lang }
                         : { cd1: lang }),
                     ...event

package/src/flags.js

@@ -18,8 +18,14 @@ const FLAG_DISAMBIGUATION_OFFERED = 'o';
  */
 const FLAG_DO_NOT_LOG = '!';
 
+/**
+ * Handover occurred
+ */
+const FLAG_HANDOVER = 'h';
+
 module.exports = {
     FLAG_DISAMBIGUATION_SELECTED,
     FLAG_DISAMBIGUATION_OFFERED,
-    FLAG_DO_NOT_LOG
+    FLAG_DO_NOT_LOG,
+    FLAG_HANDOVER
 };

package/src/utils/quickReplies.js

@@ -5,7 +5,7 @@
 
 const { makeAbsolute } = require('./pathUtils');
 const { tokenize } = require('./tokenizer');
-const { FLAG_DISAMBIGUATION_SELECTED } = require('../flags');
+const { ResponseFlag } = require('../analytics/consts');
 const { checkSetState } = require('./stateVariables');
 
 /** @typedef {import('../Request')} Request */
@@ -240,7 +240,7 @@ function makeQuickReplies (replies, path = '', translate = (w) => w, quickReplyC
             }
 
             if (data._senderMeta
-                && data._senderMeta.flag === FLAG_DISAMBIGUATION_SELECTED) {
+                && data._senderMeta.flag === ResponseFlag.DISAMBIGUATION_SELECTED) {
 
                 const { likelyIntent } = data._senderMeta;
                 disambiguationIntents.push(likelyIntent);
@@ -411,7 +411,7 @@ function disambiguationQuickReply (title, likelyIntent, disambText, action, data
         data: {
             ...data,
             _senderMeta: {
-                flag: FLAG_DISAMBIGUATION_SELECTED,
+                flag: ResponseFlag.DISAMBIGUATION_SELECTED,
                 likelyIntent,
                 disambText
             }

package/src/utils/stateVariables.js

@@ -108,9 +108,12 @@ function checkSetState (setState, newState) {
  * @returns {boolean}
  */
 function isUserInteraction (req) {
-    return req.isMessage() || req.isPostBack()
-        || req.isReferral() || req.isAttachment()
-        || req.isTextOrIntent();
+    return !req.campaign
+        && !req.event.pass_thread_control
+        && !req.isSetContext()
+        && (req.isMessage() || req.isPostBack()
+            || req.isReferral() || req.isAttachment()
+            || req.isTextOrIntent());
 }
 
 /**