@zoho_apptics/apptics-js-sdk 2.0.0-beta.1 → 2.0.0-beta.2

package/dist/cjs/device/index.d.ts

@@ -28,7 +28,22 @@ export declare function getUpdatesFromServer(): Promise<Dict>;
  */
 export declare function restoreServerSettings(): void;
 /**
- * Fetches the server settings now if the device is registered. On a first visit the ids don't
- * exist yet; registerDeviceWithApptics calls this as soon as device/add succeeds.
+ * next_check_after as a time: the server's value is milliseconds, either a timestamp or a wait
+ * from now. Anything below 1e12 (2001 as a timestamp) can only be a wait.
+ */
+export declare function nextCheckTime(value: unknown, now: number): number;
+/**
+ * Asks for the server settings now if the device is registered, then schedules the next ask
+ * for the time the answer gave in next_check_after. On a first visit the ids don't exist yet;
+ * registerDeviceWithApptics calls this as soon as device/add succeeds.
  */
 export declare function refreshServerSettings(): void;
+/**
+ * Start-up's getsdkconfig. Asked on a first visit and on the first page load in each tab; any
+ * other load (a reload, a link to another page of the site, back/forward) uses the saved answer
+ * and waits for its next_check_after, unless that has already passed. Nothing happens if one has
+ * gone out already on this load (after device/add).
+ */
+export declare function startServerSettingChecks(): void;
+/** reset(): no more checks, and the next init() asks again straight away. */
+export declare function stopServerSettingChecks(): void;

package/dist/cjs/device/index.js

@@ -1,4 +1,4 @@
-/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta.1 | (c) Zoho Corporation Private Limited | see LICENSE */
+/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta.2 | (c) Zoho Corporation Private Limited | see LICENSE */
 'use strict';
 
 var constants = require('../core/constants.js');
@@ -108,10 +108,18 @@ function checkAndUpdateDeviceInfo() {
     storage.user_defaults.add('device_info', state._ZAP._device_info); // no i18n
     addOrUpdateDeviceID(state._ZAP._device_info, previous);
 }
+/**
+ * Whether device/add has registered this device: it has a deviceid. anonymousid is not required:
+ * not every Apptics server sends one, nothing the SDK sends carries it, and requiring it had a
+ * server that leaves it out register the same device again on every page load.
+ */
+function isRegistered(info) {
+    return !!info && !utils.isEmpty(info.deviceid);
+}
 function addOrUpdateDeviceID(device_info, previous) {
     var old_device_info = previous !== undefined ? previous : storage.user_defaults.item('device_info') || {}; // no i18n
     // Compare the old and new device infos and update the server if anything changed in the new.
-    if (device_info.deviceid == null || device_info.frameworkid == null || device_info.anonymousid == null) {
+    if (!isRegistered(device_info) || device_info.frameworkid == null) {
         device_info.frameworkid = state._ZAP._frameworkID;
         logger.Console.log('addOrUpdateDeviceID: Initiated register the device'); // no i18n
         registerDeviceWithApptics().then(function (result_device_info) {
@@ -188,7 +196,7 @@ function useStoredUuid() {
 function adoptRegisteredDevice() {
     return storage.reloadSettings(['device_info']).then(function () {
         var stored = storage.user_defaults.item('device_info') || {}; // no i18n
-        if (utils.isEmpty(stored.deviceid) || utils.isEmpty(stored.anonymousid)) {
+        if (!isRegistered(stored)) {
             return null;
         }
         // the device is registered under the uuid the other tab sent
@@ -213,7 +221,7 @@ function adoptRegisteredDevice() {
  */
 function prepareDevice() {
     var cached = storage.user_defaults.item('device_info') || {}; // no i18n
-    if (!utils.isEmpty(cached.deviceid) && !utils.isEmpty(cached.anonymousid)) {
+    if (isRegistered(cached)) {
         useStoredUuid();
         checkAndUpdateDeviceInfo();
         return Promise.resolve();
@@ -278,7 +286,7 @@ function registerDeviceWithApptics() {
     if (offline) {
         return offline;
     }
-    if (state._ZAP._device_info.deviceid && state._ZAP._device_info.anonymousid) {
+    if (isRegistered(state._ZAP._device_info)) {
         return Promise.resolve(state._ZAP._device_info);
     }
     return new Promise((resolve, reject) => {
@@ -306,8 +314,10 @@ function registerDeviceWithApptics() {
         }).then(function (result) {
             settleRegistration(true, result);
             resolve(result);
-            // first visit: the ids exist now, so fetch the server settings right away
-            refreshServerSettings();
+            // first visit: the ids exist now, so fetch the server settings right away. A device
+            // registered again later (its details or the framework id changed) asks nothing more:
+            // start-up has already asked on this page load
+            startServerSettingChecks();
         }).catch(function (err) {
             settleRegistration(false, err);
             reject(err);
@@ -339,6 +349,12 @@ function getUpdatesFromServer() {
     return transport.postToApptics('sdkconfig', '', transport.apiHeaders(), label).then(function (result) {
         var data = result.data || {};
         applyServerFlags(data);
+        if (state._ZAP._nextConfigCheck === 0) {
+            // no next_check_after: getupdates_interval from now, stored so a later page load
+            // can tell whether the answer is still current
+            state._ZAP._nextConfigCheck = utils.nowMs() + state.getConfig('getupdates_interval'); // no i18n
+            state._ZAP._trackinfo.next_check_after = state._ZAP._nextConfigCheck;
+        }
         // the visitor's tracking status lives in trackinfo too, and is not the server's to replace
         var saved = storage.storedTrackingStatus();
         storage.user_defaults.add('trackinfo', saved === undefined ? state._ZAP._trackinfo : Object.assign({}, state._ZAP._trackinfo, { tracking_status: saved })); // no i18n
@@ -374,6 +390,10 @@ function applyServerFlags(data) {
     if (data.hasOwnProperty('tracking_enabled')) { // no i18n
         state._ZAP._shouldTrack = data.tracking_enabled !== false;
     }
+    else if (data.hasOwnProperty('shouldtrack')) { // no i18n
+        // what this SDK saves, read back on the next visit
+        state._ZAP._shouldTrack = data.shouldtrack !== false;
+    }
     else {
         // the old shape: archived versions and untracked customer groups
         var versionArchived = !data.hasOwnProperty('versionarchivestatus') || utils.isEmpty(data.versionarchivestatus)
@@ -383,9 +403,14 @@ function applyServerFlags(data) {
         state._ZAP._shouldTrack = versionArchived || !customerGroupTracking;
     }
     if (hasModules) {
-        // sessions carry screens, events and api calls, so module 11 gates all of engagement
-        state._ZAP._engagementTracking = moduleEnabled(status, constants.SDK_MODULE.SESSION);
-        state._ZAP._errorTracking = moduleEnabled(status, constants.SDK_MODULE.CRASH);
+        // each kind of engagement item has its own module, so the server can turn one off alone
+        state._ZAP._engagementTracking = {
+            event: moduleEnabled(status, constants.SDK_MODULE.EVENT),
+            api: moduleEnabled(status, constants.SDK_MODULE.API),
+            screen: moduleEnabled(status, constants.SDK_MODULE.SCREEN),
+            session: moduleEnabled(status, constants.SDK_MODULE.SESSION),
+        };
+        state._ZAP._errorTracking = moduleEnabled(status, constants.SDK_MODULE.JS_ERROR);
         state._ZAP._heatmapTracking = moduleEnabled(status, constants.SDK_MODULE.HEATMAP);
         state._ZAP._remoteLoggerEnabled = moduleEnabled(status, constants.SDK_MODULE.REMOTE_LOGGER);
         state._ZAP._feedbackEnabled = moduleEnabled(status, constants.SDK_MODULE.FEEDBACK);
@@ -394,11 +419,22 @@ function applyServerFlags(data) {
         state._ZAP._remoteConfigEnabled = moduleEnabled(status, constants.SDK_MODULE.REMOTE_CONFIG);
     }
     else {
-        state._ZAP._engagementTracking = data.engagementtracking !== false;
-        state._ZAP._errorTracking = data.errortracking !== false;
-        state._ZAP._heatmapTracking = data.heatmaptracking !== false;
-        state._ZAP._remoteLoggerEnabled = data.remoteloggerenabled !== false;
-        state._ZAP._feedbackEnabled = data.feedbackenabled !== false;
+        // this SDK saves one flag per kind under engagement; an earlier build saved one
+        // engagementtracking flag for all four
+        var saved = (data.engagement && typeof data.engagement === 'object' // no i18n
+            ? data.engagement : null);
+        var kindOn = function (kind) {
+            return saved ? saved[kind] !== false : data.engagementtracking !== false;
+        };
+        state._ZAP._engagementTracking = { event: kindOn('event'), api: kindOn('api'), screen: kindOn('screen'), session: kindOn('session') }; // no i18n
+        // the same for the others: read the short key this SDK saves, else the earlier build's
+        var flagOn = function (key, oldKey) {
+            return (data.hasOwnProperty(key) ? data[key] : data[oldKey]) !== false;
+        };
+        state._ZAP._errorTracking = flagOn('error', 'errortracking'); // no i18n
+        state._ZAP._heatmapTracking = flagOn('heatmap', 'heatmaptracking'); // no i18n
+        state._ZAP._remoteLoggerEnabled = flagOn('remotelogger', 'remoteloggerenabled'); // no i18n
+        state._ZAP._feedbackEnabled = flagOn('feedback', 'feedbackenabled'); // no i18n
     }
     // screen recording, set up in the console: everything the form needs comes from here
     var quartz = (data.quartz && typeof data.quartz === 'object' ? data.quartz : {});
@@ -412,16 +448,15 @@ function applyServerFlags(data) {
         domain: text(quartz.quartz_domain),
         cdnUrl: text(quartz.quartz_cdn_url),
     };
-    // when to ask again, which replaces polling on a fixed interval
-    if (typeof data.next_check_after === 'number' && data.next_check_after > 0) {
-        state._ZAP._nextConfigCheck = data.next_check_after;
-    }
+    // when to ask again, which replaces polling on a fixed interval. Kept as a timestamp, so the
+    // stored copy reads back the same. An answer without one falls back to getupdates_interval
+    state._ZAP._nextConfigCheck = nextCheckTime(data.next_check_after, utils.nowMs());
     state._ZAP._trackinfo = {
-        engagementtracking: state._ZAP._engagementTracking,
-        errortracking: state._ZAP._errorTracking,
-        heatmaptracking: state._ZAP._heatmapTracking,
-        remoteloggerenabled: state._ZAP._remoteLoggerEnabled,
-        feedbackenabled: state._ZAP._feedbackEnabled,
+        engagement: state._ZAP._engagementTracking,
+        error: state._ZAP._errorTracking,
+        heatmap: state._ZAP._heatmapTracking,
+        remotelogger: state._ZAP._remoteLoggerEnabled,
+        feedback: state._ZAP._feedbackEnabled,
         // in the server's own shape, so restoring it on the next visit reads it the same way
         quartz: {
             quartz_enabled: state._ZAP._quartz.enabled,
@@ -442,31 +477,164 @@ function restoreServerSettings() {
     var saved = storage.user_defaults.item('trackinfo'); // no i18n
     if (saved && typeof saved === 'object') { // no i18n
         applyServerFlags(saved);
+        // saved by an earlier build under the old names: store it again in this SDK's shape now,
+        // rather than at the next getsdkconfig, which may be a while off. The visitor's tracking
+        // status is kept as it is
+        if (OLD_TRACKINFO_KEYS.some(function (key) { return saved.hasOwnProperty(key); })) {
+            storage.user_defaults.add('trackinfo', saved.tracking_status === undefined ? state._ZAP._trackinfo // no i18n
+                : Object.assign({}, state._ZAP._trackinfo, { tracking_status: saved.tracking_status }));
+        }
         logger.Console.log('restoreServerSettings: ' + JSON.stringify(state._ZAP._trackinfo)); // no i18n
     }
 }
+/** trackinfo keys an earlier build saved, which this SDK saves under shorter names. */
+var OLD_TRACKINFO_KEYS = ['engagementtracking', 'errortracking', 'heatmaptracking', 'remoteloggerenabled', 'feedbackenabled']; // no i18n
+/**
+ * next_check_after as a time: the server's value is milliseconds, either a timestamp or a wait
+ * from now. Anything below 1e12 (2001 as a timestamp) can only be a wait.
+ */
+function nextCheckTime(value, now) {
+    if (typeof value !== 'number' || !(value > 0)) { // no i18n
+        return 0;
+    }
+    return value >= 1e12 ? value : now + value;
+}
+/** setTimeout's longest wait; a longer one fires straight away. */
+var MAX_TIMEOUT = 2147483647;
+var configTimer = null;
+var configInFlight = false;
+/** Bumped by stopServerSettingChecks(), so an answer to an ask from before a reset schedules nothing. */
+var configRound = 0;
+/** Whether this page load has asked, or set the timer from the saved answer instead. */
+var configAsked = false;
+/** A user registered, or getupdates reported a change, while a getsdkconfig was in flight: asked again when it answers. */
+var configAskAgain = false;
+/** When the next getsdkconfig is due, as a timestamp. 0 until the first answer. */
+var configDueAt = 0;
 /**
- * Fetches the server settings now if the device is registered. On a first visit the ids don't
- * exist yet; registerDeviceWithApptics calls this as soon as device/add succeeds.
+ * Asks for the server settings now if the device is registered, then schedules the next ask
+ * for the time the answer gave in next_check_after. On a first visit the ids don't exist yet;
+ * registerDeviceWithApptics calls this as soon as device/add succeeds.
  */
 function refreshServerSettings() {
-    if (utils.isEmpty(transport.getHeaderParams('apid')) && utils.isEmpty(transport.getHeaderParams('mapid'))) { // no i18n
+    if (configInFlight || !transport.hasDeviceId() || (utils.isEmpty(transport.getHeaderParams('apid')) && utils.isEmpty(transport.getHeaderParams('mapid')))) { // no i18n
         return;
     }
+    if (configTimer !== null) {
+        clearTimeout(configTimer);
+        configTimer = null;
+    }
+    configInFlight = true;
+    configAsked = true;
+    markTabAsked();
+    var round = configRound;
+    var askedAt = utils.nowMs();
     getUpdatesFromServer().catch(function (err) {
         logger.Console.log(err);
+    }).then(function () {
+        if (round !== configRound) {
+            // stopServerSettingChecks() ran while this was in flight
+            return;
+        }
+        configInFlight = false;
+        if (configAskAgain) {
+            configAskAgain = false;
+            refreshServerSettings();
+            return;
+        }
+        // an answer without a usable next_check_after, or a failed call, waits getupdates_interval
+        configDueAt = state._ZAP._nextConfigCheck > utils.nowMs() ? state._ZAP._nextConfigCheck : askedAt + state.getConfig('getupdates_interval'); // no i18n
+        scheduleServerSettingCheck();
     });
 }
+/**
+ * getsdkconfig now, not at the next check: setUser registered a user, or getupdates reported a
+ * module changed.
+ */
+function askServerSettings() {
+    if (configInFlight) {
+        // the one in flight went out before the change: ask again once it answers
+        configAskAgain = true;
+        return;
+    }
+    refreshServerSettings();
+}
+/**
+ * Start-up's getsdkconfig. Asked on a first visit and on the first page load in each tab; any
+ * other load (a reload, a link to another page of the site, back/forward) uses the saved answer
+ * and waits for its next_check_after, unless that has already passed. Nothing happens if one has
+ * gone out already on this load (after device/add).
+ */
+function startServerSettingChecks() {
+    if (configAsked) {
+        return;
+    }
+    if (tabHasAsked() && state._ZAP._nextConfigCheck > utils.nowMs()) {
+        logger.Console.log('getsdkconfig: the saved answer is still current'); // no i18n
+        configAsked = true;
+        configDueAt = state._ZAP._nextConfigCheck;
+        scheduleServerSettingCheck();
+        return;
+    }
+    refreshServerSettings();
+}
+/** sessionStorage: per tab, and kept across a reload and the site's own links. */
+var TAB_ASKED_KEY = '_apptics_sdkconfig_asked'; // no i18n
+/** Whether getsdkconfig has gone out in this tab before, on an earlier page load. */
+function tabHasAsked() {
+    try {
+        return sessionStorage.getItem(TAB_ASKED_KEY) === '1'; // no i18n
+    }
+    catch (e) {
+        return false; // no sessionStorage (private mode, sandboxed frame): every load asks
+    }
+}
+function markTabAsked() {
+    try {
+        sessionStorage.setItem(TAB_ASKED_KEY, '1'); // no i18n
+    }
+    catch (e) {
+        // as above: without it, every load asks
+    }
+}
+/** Sets the timer for the next getsdkconfig, at configDueAt. */
+function scheduleServerSettingCheck() {
+    if (configTimer !== null) {
+        clearTimeout(configTimer);
+    }
+    var wait = Math.min(Math.max(configDueAt - utils.nowMs(), 0), MAX_TIMEOUT);
+    logger.Console.log('getsdkconfig: next check in ' + wait + ' ms'); // no i18n
+    configTimer = setTimeout(function () {
+        configTimer = null;
+        refreshServerSettings();
+    }, wait);
+}
+/** reset(): no more checks, and the next init() asks again straight away. */
+function stopServerSettingChecks() {
+    if (configTimer !== null) {
+        clearTimeout(configTimer);
+    }
+    configTimer = null;
+    configRound++;
+    configInFlight = false;
+    configAsked = false;
+    configAskAgain = false;
+    configDueAt = 0;
+}
 hooks.hooks.updateDevice = updateDeviceWithApptics;
 hooks.hooks.refreshDeviceInfo = checkAndUpdateDeviceInfo;
+hooks.hooks.askServerSettings = askServerSettings;
 
 exports.addOrUpdateDeviceID = addOrUpdateDeviceID;
 exports.checkAndUpdateDeviceInfo = checkAndUpdateDeviceInfo;
 exports.deviceReady = deviceReady;
 exports.getUpdatesFromServer = getUpdatesFromServer;
 exports.needsDevice = needsDevice;
+exports.nextCheckTime = nextCheckTime;
 exports.prepareDevice = prepareDevice;
 exports.refreshServerSettings = refreshServerSettings;
 exports.registerDeviceWithApptics = registerDeviceWithApptics;
 exports.restoreServerSettings = restoreServerSettings;
+exports.startServerSettingChecks = startServerSettingChecks;
+exports.stopServerSettingChecks = stopServerSettingChecks;
 exports.updateDeviceWithApptics = updateDeviceWithApptics;

package/dist/cjs/engagement/api-rules.js

@@ -1,4 +1,4 @@
-/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta.1 | (c) Zoho Corporation Private Limited | see LICENSE */
+/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta.2 | (c) Zoho Corporation Private Limited | see LICENSE */
 'use strict';
 
 var logger = require('../core/logger.js');

package/dist/cjs/engagement/auto-api.js

@@ -1,4 +1,4 @@
-/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta.1 | (c) Zoho Corporation Private Limited | see LICENSE */
+/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta.2 | (c) Zoho Corporation Private Limited | see LICENSE */
 'use strict';
 
 var state = require('../core/state.js');

package/dist/cjs/engagement/auto-screen.js

@@ -1,4 +1,4 @@
-/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta.1 | (c) Zoho Corporation Private Limited | see LICENSE */
+/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta.2 | (c) Zoho Corporation Private Limited | see LICENSE */
 'use strict';
 
 var logger = require('../core/logger.js');

package/dist/cjs/engagement/defined-events.js

@@ -1,4 +1,4 @@
-/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta.1 | (c) Zoho Corporation Private Limited | see LICENSE */
+/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta.2 | (c) Zoho Corporation Private Limited | see LICENSE */
 'use strict';
 
 /**

package/dist/cjs/engagement/send.js

@@ -1,4 +1,4 @@
-/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta.1 | (c) Zoho Corporation Private Limited | see LICENSE */
+/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta.2 | (c) Zoho Corporation Private Limited | see LICENSE */
 'use strict';
 
 var constants = require('../core/constants.js');
@@ -15,8 +15,7 @@ var transport = require('../core/transport.js');
  * Sends pending engagements to the Apptics API.
  */
 function sendEngagementData(forget) {
-    // engagementtracking off (getupdates): queued items stay until tracking is back on or they expire
-    if (env.is_apptics_disabled() || !consent.shouldTrackOrSendData() || !state._ZAP._engagementTracking) {
+    if (env.is_apptics_disabled() || !consent.shouldTrackOrSendData()) {
         return Promise.resolve();
     }
     if (navigator.onLine == false) {
@@ -39,6 +38,11 @@ function sendEngagementData(forget) {
             var _payload = {};
             var sent = [];
             utils.cloneObject(engagement_items).forEach(function (item) {
+                // a kind the server has turned off (getsdkconfig's event, api, screen or session
+                // module) stays queued until it is back on or the item expires
+                if (state._ZAP._engagementTracking[item.type] === false) {
+                    return;
+                }
                 const itemWithId = { ...item };
                 if (item.type == constants.AP_CONSTANTS.EVENT) {
                     eventObj.push(item);

package/dist/cjs/engagement/session.d.ts

@@ -35,10 +35,27 @@ export declare function dropPendingSession(): boolean;
 /** Whether a session is waiting to be written. Used by tests and by the page-closing path. */
 export declare function hasPendingSession(): boolean;
 export declare function startNewSession(time: number): Promise<void>;
+/**
+ * The tab went inactive. That moment becomes the session's lastactivetime, the time it ends at if
+ * the user does not come back within inactiveduration. If they do not, the session is ended at it
+ * then, and `onEnded` sends it, rather than staying open until they return or the tab closes.
+ * Going inactive twice (a window blur, then the tab hidden) keeps the first moment.
+ */
+export declare function markTabInactive(onEnded: () => void): Promise<void>;
+/**
+ * The tab is active again. The caller then settles the session (checkAndUpdateSession): back
+ * within inactiveduration it continues, later it has ended and a new one starts.
+ */
+export declare function markTabActive(): void;
+/** reset(): no timer left running, and the tab counts as active. */
+export declare function resetInactivity(): void;
 /**
  * This tab is closing, or the page is being replaced. The session ends here when this is the last
  * tab using it, so it can be sent; while another tab of the site is still on it, this tab only
  * leaves it, and the last tab to close ends it. Nothing happens when it is already closed.
+ *
+ * A tab closed while inactive ends the session when the user left (its lastactivetime), not when
+ * the tab closed: the time it sat hidden or in the background is not session time.
  */
 export declare function endCurrentSession(): Promise<void>;
 /**

package/dist/cjs/engagement/session.js

@@ -1,4 +1,4 @@
-/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta.1 | (c) Zoho Corporation Private Limited | see LICENSE */
+/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta.2 | (c) Zoho Corporation Private Limited | see LICENSE */
 'use strict';
 
 var constants = require('../core/constants.js');
@@ -64,7 +64,7 @@ function closeScreensOf(session, time) {
  * @param sessionData A set of properties belonging to the session.
  */
 function trackSession(sessionData) {
-    if (!consent.canTrackEngagement('trackSession')) { // no i18n
+    if (!consent.canTrackEngagement('trackSession', constants.AP_CONSTANTS.SESSION)) { // no i18n
         return Promise.resolve();
     }
     if (sessionData && typeof sessionData !== 'object') { // no i18n
@@ -320,26 +320,114 @@ function commitNow(session) {
     }
     return trackSession(session);
 }
+/** Whether this tab is inactive: hidden, minimised, or its window has lost focus. */
+var inactive = false;
+var inactivityTimer = null;
+/**
+ * The tab went inactive. That moment becomes the session's lastactivetime, the time it ends at if
+ * the user does not come back within inactiveduration. If they do not, the session is ended at it
+ * then, and `onEnded` sends it, rather than staying open until they return or the tab closes.
+ * Going inactive twice (a window blur, then the tab hidden) keeps the first moment.
+ */
+function markTabInactive(onEnded) {
+    var first = !inactive;
+    inactive = true;
+    if (inactivityTimer !== null) {
+        clearTimeout(inactivityTimer);
+    }
+    inactivityTimer = setTimeout(function () {
+        inactivityTimer = null;
+        endInactiveSession().then(function (ended) {
+            if (ended) {
+                onEnded();
+            }
+        });
+    }, state._ZAP.inactiveduration * 60 * 1000 + 1000);
+    return first ? updateLastActiveTimeOfSession() : Promise.resolve();
+}
+/**
+ * The tab is active again. The caller then settles the session (checkAndUpdateSession): back
+ * within inactiveduration it continues, later it has ended and a new one starts.
+ */
+function markTabActive() {
+    inactive = false;
+    if (inactivityTimer !== null) {
+        clearTimeout(inactivityTimer);
+        inactivityTimer = null;
+    }
+}
+/** reset(): no timer left running, and the tab counts as active. */
+function resetInactivity() {
+    markTabActive();
+}
+/**
+ * inactiveduration has passed with the tab inactive: the session ends at its lastactivetime, when
+ * the user left, so the time away is not counted. Resolves true when it ended one. While another
+ * tab of the site is still on the session, this tab only leaves it; one whose lastactivetime is
+ * recent is in use elsewhere and is left alone.
+ */
+function endInactiveSession() {
+    if (!state._ZAP._token || env.is_apptics_disabled()) {
+        return Promise.resolve(false);
+    }
+    var ended = false;
+    return withSessionLock(function () {
+        return currentSession().then(function (_currentSession) {
+            if (!_currentSession || _currentSession.endtime !== 0) {
+                return;
+            }
+            var lastActive = Number(_currentSession.lastactivetime) || utils.nowMs();
+            if (utils.nowMs() - lastActive < state._ZAP.inactiveduration * 60 * 1000) {
+                return;
+            }
+            var others = tabsOf(_currentSession).filter(function (tab) { return tab !== tabId(); });
+            if (others.length > 0) {
+                var left = Object.assign({}, _currentSession, { tabs: others });
+                state._ZAP._current_session = left;
+                return storage.engagement_transactions.update(left);
+            }
+            var endAt = Math.max(lastActive, Number(_currentSession.starttime) || lastActive);
+            var closed = Object.assign({}, _currentSession, { endtime: endAt, tabs: [] });
+            state._ZAP._current_session = closed;
+            ended = true;
+            logger.Console.log('session: inactive for ' + state._ZAP.inactiveduration + ' minutes, so it ends when the user left, ' + endAt); // no i18n
+            return storage.engagement_transactions.update(closed).then(function () {
+                return closeScreensOf(closed, endAt);
+            });
+        });
+    }).then(function () {
+        return ended;
+    });
+}
 /**
  * This tab is closing, or the page is being replaced. The session ends here when this is the last
  * tab using it, so it can be sent; while another tab of the site is still on it, this tab only
  * leaves it, and the last tab to close ends it. Nothing happens when it is already closed.
+ *
+ * A tab closed while inactive ends the session when the user left (its lastactivetime), not when
+ * the tab closed: the time it sat hidden or in the background is not session time.
  */
 function endCurrentSession() {
     var time = utils.nowMs();
+    var wasInactive = inactive;
+    markTabActive();
     // nothing was tracked and the minimum was never reached: this visit is not reported at all
     if (dropPendingSession()) {
         return Promise.resolve();
     }
     return withSessionLock(function () {
-        return closeOrLeaveSession(time);
+        return closeOrLeaveSession(time, wasInactive);
     });
 }
-function closeOrLeaveSession(time) {
+function closeOrLeaveSession(now, wasInactive) {
     return currentSession().then(function (_currentSession) {
         if (!_currentSession || _currentSession.endtime !== 0) {
             return;
         }
+        var lastActive = Number(_currentSession.lastactivetime) || 0;
+        var time = wasInactive && lastActive > 0
+            ? Math.max(Math.min(lastActive, now), Number(_currentSession.starttime) || 0)
+            : now;
         var others = tabsOf(_currentSession).filter(function (tab) { return tab !== tabId(); });
         if (others.length > 0) {
             var left = Object.assign({}, _currentSession, { tabs: others, lastactivetime: time });
@@ -456,6 +544,9 @@ exports.currentSession = currentSession;
 exports.dropPendingSession = dropPendingSession;
 exports.endCurrentSession = endCurrentSession;
 exports.holdTabLock = holdTabLock;
+exports.markTabActive = markTabActive;
+exports.markTabInactive = markTabInactive;
+exports.resetInactivity = resetInactivity;
 exports.startNewSession = startNewSession;
 exports.tabId = tabId;
 exports.trackSession = trackSession;

package/dist/cjs/engagement/track.d.ts

@@ -1,12 +1,12 @@
 import type { Dict, Properties } from '../types.js';
 import { type DefinedEvent } from './defined-events.js';
 /**
- * Records an event: `trackEvent(name, group?, properties?)`, or a defined event with
+ * Records an event: `trackEvent(name, group, properties?)`, or a defined event with
  * `trackEvent(DefinedEvents.AP_USER_LOGIN, properties?)`, which brings its own group.
  *
- * As on Android, an invalid name or group is not logged. A group left out is `default`, so the
- * one-argument form keeps working; a group given but invalid is a mistake worth being told about,
- * not one to file quietly under `default`.
+ * The group is required. An event without one, or with an invalid name or group, is not logged,
+ * and the console says why (debug or not): filing it under a group the app never named would hide
+ * the mistake.
  */
 export declare function trackEvent(eventName: string | DefinedEvent, groupName?: string | Properties, jsonObj?: Properties): void;
 /** The app's own screen view. Automatic screen tracking calls recordScreen() instead. */