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

package/dist/esm/lifecycle.js

@@ -1,25 +1,24 @@
-/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta | (c) Zoho Corporation Private Limited | see LICENSE */
-import { REQUIRED_CONFIG, AP_CONFIG, CONFIG_ALIASES, DEFAULT_INACTIVE_MINUTES } from './core/constants.js';
+/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta.2 | (c) Zoho Corporation Private Limited | see LICENSE */
+import { REQUIRED_CONFIG, CONFIG_KEYS, AP_CONFIG, RETIRED_CONFIG_NAMES, DEFAULT_INACTIVE_MINUTES } from './core/constants.js';
 import { _ZAP } from './core/state.js';
-import { warnAlways, Console } from './core/logger.js';
-import { isEmpty, getNewUUID, isSuccess } from './core/utils.js';
-import { storageReady, user_defaults, tracking_preference, engagement_transactions, error_transactions } from './core/storage.js';
+import { Console, warnAlways } from './core/logger.js';
+import { isEmpty, isSuccess } from './core/utils.js';
+import { storageReady, user_defaults, engagement_transactions, error_transactions, heatmap_transactions, remotelog_transactions, feedbacklog_transactions, tracking_preference } from './core/storage.js';
 import { hooks } from './core/hooks.js';
 import { applyDebugConfig } from './core/debug.js';
 import { getConnectionType, getOrientation } from './core/env.js';
-import { getTrackingStatus } from './core/consent.js';
-import { restoreServerSettings, checkAndUpdateDeviceInfo, refreshServerSettings, updateDeviceWithApptics, needsDevice, deviceReady } from './device/index.js';
-import { registerAppVersion, clearAppVersion } from './device/appversion.js';
-import { checkAndUpdateSession, updateLastActiveTimeOfSession, updateScreenWithEndtime, endCurrentSession } from './engagement/session.js';
+import { restoreServerSettings, prepareDevice, startServerSettingChecks, updateDeviceWithApptics, needsDevice, deviceReady } from './device/index.js';
+import { clearAppVersion, keyFingerprint, registerAppVersion, appVersionFailedForNetwork } from './device/appversion.js';
+import { holdTabLock, checkAndUpdateSession, markTabInactive, markTabActive, updateScreenWithEndtime, endCurrentSession, resetInactivity } from './engagement/session.js';
 import { enableApiTracking } from './engagement/auto-api.js';
-import { enableScreenTracking } from './engagement/auto-screen.js';
+import { enableScreenTracking, routePath } from './engagement/auto-screen.js';
 import { resumeScreen, trackEvent } from './engagement/track.js';
 import { trackError } from './errors/track.js';
 import { startTimers, flush, stopTimers } from './scheduler.js';
-import './remotelog/index.js';
+import { sendStoredLogs, forgetStoredLogs } from './remotelog/send.js';
 import { getUserInfo } from './user/index.js';
 import { clearAttempts } from './core/attempts.js';
-import { sendStoredLogs, forgetStoredLogs } from './remotelog/send.js';
+import { FRAMEWORK_ID } from './core/framework-id.js';
 
 let listenersAttached = false;
 /** The config init() was last called with; reset() starts again from it. */
@@ -38,16 +37,29 @@ function isBrowser() {
     }
 }
 /**
- * Canonical config: serviceUrl, zak, identifier, appversion.
- * The console snippet uses older names (base_domain, token), which are accepted here.
- * serviceUrl loses any trailing slash, because request paths add their own.
+ * The config as the SDK keeps it: base_url, auth_key and app_domain under their inside names
+ * (serviceUrl, zak, identifier; see CONFIG_KEYS), and appversion as text. An earlier name of a
+ * key is still read when the key itself is not given, with a warning naming the key to use.
+ * The base url loses any trailing slash, because request paths add their own.
  */
 function normaliseConfig(config) {
     var settings = Object.assign({}, config);
-    Object.keys(CONFIG_ALIASES).forEach(function (key) {
-        if (isEmpty(settings[key]) && !isEmpty(settings[CONFIG_ALIASES[key]])) {
-            settings[key] = settings[CONFIG_ALIASES[key]];
+    Object.keys(CONFIG_KEYS).forEach(function (key) {
+        var inside = CONFIG_KEYS[key];
+        if (!isEmpty(config[key])) {
+            settings[inside] = config[key];
+            return;
         }
+        delete settings[inside];
+        Object.keys(RETIRED_CONFIG_NAMES).forEach(function (old) {
+            if (RETIRED_CONFIG_NAMES[old] !== key || isEmpty(config[old])) {
+                return;
+            }
+            warnAlways('Apptics.init: ' + old + ' is now ' + key + '; rename it in your config'); // no i18n
+            if (isEmpty(settings[inside])) {
+                settings[inside] = config[old];
+            }
+        });
     });
     if (!isEmpty(settings.serviceUrl)) {
         settings.serviceUrl = String(settings.serviceUrl).replace(/\/+$/, ''); // no i18n
@@ -73,21 +85,62 @@ const APPVERSION_PLACEHOLDERS = ['YOUR_APP_VERSION', 'YOUR_BUILD_OR_APP_VERSION'
 function isAppVersionPlaceholder(version) {
     return APPVERSION_PLACEHOLDERS.indexOf(version.toUpperCase()) !== -1;
 }
+/**
+ * The framework id this SDK reports to serviceUrl. The id built into the package is the one
+ * sdk-apptics.zoho.com issued at publish time, and localzoho servers don't know it: any
+ * localzoho serviceUrl reports 5970 instead, the id apptics.localzoho.com issued for 2.0.0-beta
+ * (Browser), so the same package also runs there.
+ */
+const LOCALZOHO_FRAMEWORK_ID = 5970;
+function frameworkIdFor(serviceUrl) {
+    var host = serviceUrl;
+    try {
+        host = new URL(serviceUrl).hostname;
+    }
+    catch (err) {
+        // not a url: judge the text as it is
+    }
+    return host.indexOf('localzoho') !== -1 ? LOCALZOHO_FRAMEWORK_ID : FRAMEWORK_ID; // no i18n
+}
 /** Which app this browser's stored data belongs to, before app/addversion has named it. */
 function appKey(settings) {
     return settings.serviceUrl + '|' + settings.identifier; // no i18n
 }
+/**
+ * The app version stored data belongs to, read before app/addversion replaces it: what tells a
+ * new release of the app from a reload. '' on a first visit.
+ */
+var previousAppVersion = ''; // no i18n
 /**
  * Data stored for another app on this origin is discarded before anything else reads it,
  * including the stored app/addversion answer that would otherwise hand out that app's ids.
+ *
+ * Another app is a different base_url, app_domain or auth_key from the ones the stored data was
+ * registered with. Everything goes, the queues included, and start-up runs as on a first visit:
+ * app/addversion, device/add and the rest. Resolves once the store is empty.
  */
 function discardOtherAppData(settings) {
-    var stored = user_defaults.item('appkey'); // no i18n
-    if (!isEmpty(stored) && stored !== appKey(settings)) {
-        Console.log('init: stored data belongs to another app, resetting'); // no i18n
-        clearStorage();
+    // which app it is, and which version, are in app_version_info (serviceUrl, identifier, a
+    // fingerprint of zak, and appversion): no keys of their own. 2.0.0-beta's appkey and
+    // appversion are read this once
+    var info = user_defaults.item('app_version_info') || {}; // no i18n
+    var stored = !isEmpty(info.serviceUrl) && !isEmpty(info.identifier)
+        ? appKey(info)
+        : user_defaults.item('appkey'); // no i18n
+    previousAppVersion = String((!isEmpty(info.appversion) ? info.appversion : user_defaults.item('appversion')) || ''); // no i18n
+    user_defaults.add('appkey', undefined); // no i18n
+    user_defaults.add('appversion', undefined); // no i18n
+    var otherApp = !isEmpty(stored) && stored !== appKey(settings);
+    // a build that kept no fingerprint cannot tell: hasAppVersion() registers again, and records one
+    var otherKey = !isEmpty(info.zakhash) && info.zakhash !== keyFingerprint(settings.zak);
+    if (!otherApp && !otherKey) {
+        return Promise.resolve();
     }
-    user_defaults.add('appkey', appKey(settings)); // no i18n
+    Console.log('init: stored data was registered with another ' + (otherApp ? 'base_url or app_domain' : 'auth_key') + ', clearing it and starting as a first visit'); // no i18n
+    previousAppVersion = ''; // no i18n
+    // the remote config values read from the store, which is about to go
+    hooks.resetRemoteConfig();
+    return clearStorage();
 }
 /**
  * Timing an app may tune in init(). Each has a range: a value outside it is ignored with a
@@ -131,27 +184,32 @@ function applyIntervals(config) {
         }
     }
 }
+/** Everything the SDK stores: settings, ids and every queue. Resolves once it is all gone. */
 function clearStorage() {
     clearAttempts();
     user_defaults.clear();
-    engagement_transactions.clear();
-    error_transactions.clear();
+    return Promise.all([
+        engagement_transactions, error_transactions, heatmap_transactions, remotelog_transactions, feedbacklog_transactions,
+    ].map(function (queue) {
+        return queue.clear();
+    })).then(function () {
+        return undefined;
+    });
 }
 /**
- * Starts the SDK. The config object is required: pass it directly, or let the console snippet
- * supply it (auto-init reads window.appticssettings._defaultoptions and calls init with it).
- * Returns true when the config has serviceUrl, zak, identifier and appversion and start-up has
+ * Starts the SDK. The config object is required: the SDK starts only when the app calls this.
+ * Returns true when the config has base_url, auth_key, app_domain and appversion and start-up has
  * begun (see ready()), false when it was already running, the config is missing or incomplete, or
  * there is no browser. Start-up calls app/addversion with those four, which answers with aaid, the
  * portal and project ids and the rest; then device/add registers the browser, as in 1.x.
  */
 function init(config) {
     if (!config || typeof config !== 'object') { // no i18n
-        warnAlways('Apptics.init: a config object is required, e.g. apptics.init({ serviceUrl, zak, identifier, appversion })'); // no i18n
+        warnAlways('Apptics.init: a config object is required, e.g. Apptics.init({ base_url, auth_key, app_domain, appversion })'); // no i18n
         return false;
     }
     if (_ZAP._initialised) {
-        Console.warn('Apptics.init: already initialised; call apptics.reset() to start again'); // no i18n
+        Console.warn('Apptics.init: already initialised; call Apptics.reset() to start again'); // no i18n
         return false;
     }
     if (!isBrowser()) {
@@ -160,7 +218,7 @@ function init(config) {
     }
     var settings = normaliseConfig(config);
     var missing = REQUIRED_CONFIG.filter(function (key) {
-        return isEmpty(settings[key]);
+        return isEmpty(settings[CONFIG_KEYS[key] || key]);
     });
     if (missing.length > 0) {
         warnAlways('Apptics.init: missing required config: ' + missing.join(', ')); // no i18n
@@ -174,16 +232,14 @@ function init(config) {
     _ZAP._defaultoptions = settings;
     // every request goes to serviceUrl; there is no other host to learn about
     _ZAP._defaultoptions.base_domain = settings.serviceUrl;
+    // decided per init(), so a reset() or a page on another host never keeps the last one
+    _ZAP._frameworkID = frameworkIdFor(settings.serviceUrl);
     // marks the SDK as started for the checks that need it; app/addversion replaces it with aaid
     _ZAP._token = settings.identifier;
     // console_log: the SDK's own activity in the browser console
     if (!isEmpty(config.console_log)) {
         _ZAP._config.debug = !!config.console_log;
     }
-    // track_session: false records no sessions, as Android's automaticSessionsTrackingStatus
-    _ZAP._config.track_session = typeof config.track_session === 'boolean' ? config.track_session : AP_CONFIG.track_session; // no i18n
-    // show_logs: the app's own logger lines in the browser console, as Android's showLogs
-    _ZAP._config.show_logs = typeof config.show_logs === 'boolean' ? config.show_logs : AP_CONFIG.show_logs; // no i18n
     if (typeof config.ignore_do_not_track === 'boolean') { // no i18n
         _ZAP._config.ignore_do_not_track = config.ignore_do_not_track;
     }
@@ -196,10 +252,14 @@ function init(config) {
     applyDebugConfig(_ZAP._config.debug_api);
     // what to call this device in the debug stream; see devicename in core/transport.ts
     _ZAP._config.device_name = typeof config.device_name === 'string' ? config.device_name : AP_CONFIG.device_name; // no i18n
-    // remote logging: the SDK's own diagnostics, sent to console/addlog
-    _ZAP._config.remote_log = AP_CONFIG.remote_log;
-    if (typeof config.remote_log === 'boolean') { // no i18n
-        _ZAP._config.remote_log = config.remote_log;
+    // the SDK no longer reports its own failures to the Remote Logger page: only the lines an app
+    // logs with AppticsLogger go there
+    if (config.remote_log !== undefined) {
+        warnAlways('Apptics.init: remote_log is no longer read; the Remote Logger page shows the lines your app logs with AppticsLogger'); // no i18n
+    }
+    // AppticsLogger lines go to the Remote Logger page only, never to the browser console
+    if (config.show_logs !== undefined) {
+        warnAlways('Apptics.init: show_logs is no longer read; AppticsLogger lines are not printed to the browser console'); // no i18n
     }
     // automatic api tracking: the app's own requests, wrapped. Which hosts it records is
     // configureApiTracking's to say; the two keys that once did it are refused out loud rather
@@ -207,22 +267,42 @@ function init(config) {
     _ZAP._config.track_api = AP_CONFIG.track_api;
     ['track_api_hosts', 'track_api_exclude_hosts'].forEach(function (key) {
         if (config[key] !== undefined) {
-            warnAlways('Apptics.init: ' + key + ' is no longer supported; use configureApiTracking(new ApiTrackingBuilder().' // no i18n
+            warnAlways('Apptics.init: ' + key + ' is no longer supported; use AppticsApi.configure(new AppticsApi.ApiTrackingBuilder().' // no i18n
                 + (key === 'track_api_hosts' ? 'allowOnlyDomains' : 'ignoreDomains') + '(...).build())'); // no i18n
         }
     });
+    // screen recording is set up in the console now, and arrives with getsdkconfig
+    ['DC', 'quartz_workspace_key', 'quartz_department_key'].forEach(function (key) {
+        if (config[key] !== undefined) {
+            warnAlways('Apptics.init: ' + key + ' is no longer read; screen recording in the feedback form is set up from the Apptics console'); // no i18n
+        }
+    });
+    // sessions are what everything else is recorded in; an app that wants nothing tracked uses
+    // AppticsSettings.setTrackingStatus instead
+    if (config.track_session !== undefined) {
+        warnAlways('Apptics.init: track_session is no longer read; sessions are always recorded. To stop tracking, use AppticsSettings.setTrackingStatus(AppticsSettings.AP_TRACKING_STATUS.NO_TRACKING)'); // no i18n
+    }
     if (typeof config.track_api === 'boolean') { // no i18n
         _ZAP._config.track_api = config.track_api;
     }
     enableApiTracking(_ZAP._config.track_api);
-    // heatmap capture: a no-op unless the app imported the heatmap entry, which sets the hook
+    // heatmap capture: switched through the hook heatmap/track.ts sets
     _ZAP._config.track_heatmap = typeof config.track_heatmap === 'boolean' // no i18n
         ? config.track_heatmap
         : AP_CONFIG.track_heatmap;
-    hooks.enableHeatmap(_ZAP._config.track_heatmap);
+    hooks.trackHeatmap(_ZAP._config.track_heatmap);
     // automatic screen tracking, on unless the config says false: switched on by start(), once a
     // screen view can be stored
     _ZAP._config.track_screen = typeof config.track_screen === 'boolean' ? config.track_screen : AP_CONFIG.track_screen; // no i18n
+    _ZAP._config.screen_routes = screenRouteRules(config.screen_routes);
+    // uncaught errors and tagged clicks, on unless the config says false: the listeners check
+    // these as each error or click happens
+    _ZAP._config.track_error = typeof config.track_error === 'boolean' ? config.track_error : AP_CONFIG.track_error; // no i18n
+    _ZAP._config.track_click = typeof config.track_click === 'boolean' ? config.track_click : AP_CONFIG.track_click; // no i18n
+    // a theme in the config wins; without one, what AppticsFeedback.setFeedbackTheme set stays
+    if (config.feedback_theme === 'light' || config.feedback_theme === 'dark' || config.feedback_theme === 'auto') { // no i18n
+        _ZAP._config.feedback_theme = config.feedback_theme;
+    }
     applyIntervals(config);
     lastConfig = config;
     _ZAP._initialised = true;
@@ -240,22 +320,11 @@ function init(config) {
             _ZAP._pending = [];
             return false;
         }
-        discardOtherAppData(_ZAP._defaultoptions);
-        // app/addversion is the first call and everything waits on it: it is what turns the four
-        // values init() was given into aaid, the portal and project ids every url carries, and
-        // appreleaseversionid, which metaWebSDKV2 refuses a payload without
-        return registerAppVersion().then(function (registered) {
+        return discardOtherAppData(_ZAP._defaultoptions).then(function () {
             if (myGeneration !== generation) {
                 return false;
             }
-            if (!registered) {
-                warnAlways('Apptics.init: app/addversion did not return the app ids, not starting'); // no i18n
-                _ZAP._initialised = false;
-                _ZAP._token = ''; // no i18n
-                _ZAP._pending = [];
-                return false;
-            }
-            return start(config, myGeneration);
+            return startUp(config, myGeneration);
         });
     }).catch(function (err) {
         Console.error('Apptics.init: start-up failed', err); // no i18n
@@ -263,42 +332,177 @@ function init(config) {
     });
     return true;
 }
+/** Start-up from app/addversion on, once the store holds only this app's data. */
+function startUp(config, myGeneration) {
+    // app/addversion is the first call and everything waits on it: it is what turns the four
+    // values init() was given into aaid, the portal and project ids every url carries, and
+    // appreleaseversionid, which metaWebSDKV2 refuses a payload without
+    return registerAppVersion().then(function (registered) {
+        if (myGeneration !== generation) {
+            return false;
+        }
+        if (!registered && appVersionFailedForNetwork()) {
+            // a first visit with no network: start once it is back, keeping what the app
+            // tracks until then queued, rather than giving up for the rest of the page
+            warnAlways('Apptics.init: offline, so app/addversion is tried again when the browser is back online; calls made until then are kept'); // no i18n
+            return registerWhenOnline(myGeneration).then(function (ok) {
+                if (myGeneration !== generation) {
+                    return false;
+                }
+                if (!ok) {
+                    _ZAP._initialised = false;
+                    _ZAP._token = ''; // no i18n
+                    _ZAP._pending = [];
+                    return false;
+                }
+                return start(config, myGeneration);
+            });
+        }
+        if (!registered) {
+            warnAlways('Apptics.init: app/addversion did not return the app ids, not starting'); // no i18n
+            _ZAP._initialised = false;
+            _ZAP._token = ''; // no i18n
+            _ZAP._pending = [];
+            return false;
+        }
+        return start(config, myGeneration);
+    });
+}
+/** How often a start-up waiting on the network tries app/addversion again, besides on `online`. */
+const OFFLINE_RETRY_MS = 60 * 1000;
+/**
+ * app/addversion again once the network is back: on the `online` event, and every minute for a
+ * network that came back without one. Resolves true once registered, false when the server
+ * refuses it or a reset()/new init() took over.
+ */
+function registerWhenOnline(myGeneration) {
+    return new Promise(function (resolve) {
+        var timer = null;
+        var trying = false;
+        function done(ok) {
+            window.removeEventListener('online', attempt); // no i18n
+            if (timer !== null)
+                clearInterval(timer);
+            resolve(ok);
+        }
+        function attempt() {
+            if (myGeneration !== generation) {
+                done(false);
+                return;
+            }
+            if (trying || navigator.onLine === false) {
+                return;
+            }
+            trying = true;
+            registerAppVersion().then(function (registered) {
+                trying = false;
+                if (registered) {
+                    done(true);
+                }
+                else if (!appVersionFailedForNetwork()) {
+                    warnAlways('Apptics.init: app/addversion did not return the app ids, not starting'); // no i18n
+                    done(false);
+                }
+            });
+        }
+        window.addEventListener('online', attempt); // no i18n
+        timer = setInterval(attempt, OFFLINE_RETRY_MS);
+    });
+}
+/**
+ * screen_routes as init() keeps it: each entry checked, an exact path cleaned up, a regex given as
+ * a string compiled. An entry that cannot be used is left out, and said, rather than matching
+ * something its author did not mean.
+ */
+function screenRouteRules(routes) {
+    if (!Array.isArray(routes)) {
+        return [];
+    }
+    var out = [];
+    routes.forEach(function (route) {
+        if (typeof route === 'string') { // no i18n
+            if (route.trim() !== '') { // no i18n
+                out.push({ kind: 'pattern', pattern: route.trim() }); // no i18n
+            }
+            return;
+        }
+        var rule = route && typeof route === 'object' ? route : null; // no i18n
+        var name = rule && typeof rule.name === 'string' ? rule.name.trim() : ''; // no i18n
+        if (rule && name !== '' && typeof rule.equals === 'string' && rule.equals.trim() !== '') { // no i18n
+            out.push({ kind: 'equals', path: routePath(rule.equals.trim()), name: name }); // no i18n
+            return;
+        }
+        if (rule && name !== '' && rule.regex !== undefined) {
+            var regex = null;
+            if (rule.regex instanceof RegExp) {
+                regex = rule.regex;
+            }
+            else if (typeof rule.regex === 'string' && rule.regex !== '') { // no i18n
+                try {
+                    regex = new RegExp(rule.regex);
+                }
+                catch (err) {
+                    regex = null;
+                }
+            }
+            if (regex) {
+                out.push({ kind: 'regex', regex: regex, name: name }); // no i18n
+                return;
+            }
+        }
+        warnAlways('Apptics.init: screen_routes entry ' + safeJson(route) + ' is left out: give a route pattern, { equals, name } or { regex, name }'); // no i18n
+    });
+    return out;
+}
+/** An entry as the warning shows it: a RegExp as its source, which JSON.stringify would hide. */
+function safeJson(value) {
+    try {
+        return JSON.stringify(value, function (_key, one) { return one instanceof RegExp ? String(one) : one; }) || String(value);
+    }
+    catch (err) {
+        return String(value);
+    }
+}
 /** Resolves true once start-up has finished, false if init() refused or storage is unusable. */
 function ready() {
     return _ZAP._readyPromise || Promise.resolve(false);
 }
 function start(config, myGeneration) {
+    // this tab's lock, before any screen view: it is how other tabs tell this one is still open
+    holdTabLock();
     // app/addversion named the app; data stored for another one was discarded before it ran
     _ZAP._token = String(_ZAP._defaultoptions.aaid);
-    user_defaults.add('token', _ZAP._token); // no i18n
     // last known server settings (getupdates) apply before anything is tracked
     restoreServerSettings();
-    // required by init(), so _defaultoptions.appversion is always the app's own version, as the
-    // text normaliseConfig made of it: there is no default to fall back to, and the stored value
-    // below is kept only to notice when the version changes
-    var uuid = user_defaults.item('uuid'); // no i18n
-    if (isEmpty(uuid)) {
-        uuid = getNewUUID();
-        user_defaults.add('uuid', uuid); // no i18n
-    }
-    _ZAP._uuid = uuid;
-    var stored_appversion = user_defaults.item('appversion'); // no i18n
-    if (isEmpty(stored_appversion)) {
-        user_defaults.add('appversion', _ZAP._defaultoptions.appversion); // no i18n
-        stored_appversion = _ZAP._defaultoptions.appversion;
-    }
-    var appVersionChanged = stored_appversion != _ZAP._defaultoptions.appversion;
+    // the user this browser was tracking as, before getsdkconfig is asked: it carries their ids
+    getUserInfo();
+    // a new release of the app, against the version the stored data was for (see
+    // discardOtherAppData): a first visit has none, and is no change
+    var appVersionChanged = previousAppVersion !== '' && previousAppVersion != _ZAP._defaultoptions.appversion; // no i18n
     _ZAP._ignoreDnt = _ZAP._config.ignore_do_not_track;
-    tracking_preference.update_status(getTrackingStatus());
-    checkAndUpdateDeviceInfo();
-    // returning visit: ask the server for its settings now instead of waiting 2 minutes
-    // (first visit: device/add triggers it once the ids exist)
-    refreshServerSettings();
+    // the visitor's own stored choice, not getTrackingStatus(): that answers NO_TRACKING while Do
+    // Not Track is on, and storing it made one such visit switch tracking off for good
+    tracking_preference.update_status(tracking_preference.opt_in_status());
+    // the uuid and device info, and a registration on a first visit, under a lock shared with the
+    // site's other tabs (see prepareDevice)
+    return prepareDevice().then(function () {
+        if (myGeneration !== generation) {
+            return false;
+        }
+        return startTracking(appVersionChanged, myGeneration);
+    });
+}
+/** The rest of start-up, once the device is set up. */
+function startTracking(appVersionChanged, myGeneration) {
+    // getsdkconfig, once per page load and then at each answer's next_check_after. A first visit
+    // asked as soon as device/add succeeded (registerDeviceWithApptics) and this does nothing; a
+    // returning visit, whose device is registered, asks now, after app/addversion. Until it
+    // answers, the settings saved by the last visit apply (restoreServerSettings, in start())
+    startServerSettingChecks();
     if (appVersionChanged) {
         _ZAP._device_info.appversionid = ''; // no i18n
         updateDeviceWithApptics(_ZAP._device_info).then(function (result) {
             if (isSuccess(result)) {
-                user_defaults.add('appversion', _ZAP._defaultoptions.appversion); // no i18n
                 Console.log('init: appversion updated to ' + _ZAP._defaultoptions.appversion); // no i18n
             }
         }).catch(function (err) {
@@ -309,7 +513,6 @@ function start(config, myGeneration) {
     _ZAP._device_info.connectionType = getConnectionType();
     attachListeners();
     _ZAP._properties.orientation = getOrientation();
-    getUserInfo();
     return checkAndUpdateSession().then(function () {
         if (myGeneration !== generation) {
             return false;
@@ -344,12 +547,13 @@ function start(config, myGeneration) {
 function reset() {
     generation++;
     stopTimers();
+    resetInactivity();
     // the wrappers come off with everything else; the init() below puts them back if the config
     // asked for them, so a reset that has no config to restore leaves XHR and fetch untouched
     enableApiTracking(false);
     enableScreenTracking(false);
     clearAppVersion();
-    hooks.enableHeatmap(false);
+    hooks.trackHeatmap(false);
     hooks.resetHeatmap();
     hooks.resetRemoteConfig();
     clearStorage();
@@ -365,7 +569,7 @@ function reset() {
     _ZAP._apid = ''; // no i18n
     _ZAP._mapid = ''; // no i18n
     _ZAP._sending = false;
-    Console.log('apptics.reset()'); // no i18n
+    Console.log('Apptics.reset()'); // no i18n
     // start again with the config init() was called with
     if (lastConfig) {
         init(lastConfig);
@@ -374,9 +578,42 @@ function reset() {
 function isActive() {
     return _ZAP._ready;
 }
-// Declarative click tracking: <el apeventaction="name" apeventprops='{"k":"v"}'> inside <el apgroupaction="group">
+/**
+ * AppticsEvent.setClickTracking: click tracking from markup on or off, as the `track_click`
+ * config sets it. The listener stays; it checks the switch on every click.
+ */
+function setClickTracking(enabled) {
+    _ZAP._config.track_click = typeof enabled === 'boolean' ? enabled : true; // no i18n
+    Console.log('click tracking: ' + (_ZAP._config.track_click ? 'on' : 'off')); // no i18n
+}
+/**
+ * AppticsScreen.setScreenTracking: automatic screen tracking on or off, as the `track_screen`
+ * config sets it. Applied now once the SDK is running; before that it is only noted, and start()
+ * switches tracking to it. Like the other switches, the next init() (a reset() too) goes back to
+ * what its config says.
+ */
+function setScreenTracking(enabled) {
+    _ZAP._config.track_screen = typeof enabled === 'boolean' ? enabled : true; // no i18n
+    if (isActive()) {
+        enableScreenTracking(_ZAP._config.track_screen);
+    }
+}
+/**
+ * A click-tracking attribute, in either spelling: `apeventaction`, or `data-apeventaction`, which
+ * is valid HTML and what React and TypeScript accept without declaring the attribute.
+ */
+function trackingAttribute(el, name) {
+    var value = el.getAttribute(name);
+    return value !== null && value !== '' ? value : el.getAttribute('data-' + name); // no i18n
+}
+/** `[name]` and `[data-name]`, empty values left out, for closest(). */
+function trackingSelector(name) {
+    return '[' + name + ']:not([' + name + '=""]),[data-' + name + ']:not([data-' + name + '=""])'; // no i18n
+}
+// Declarative click tracking: <el apeventaction="name" apeventprops='{"k":"v"}'> inside <el apgroupaction="group">,
+// or the same attributes with a data- prefix
 function onDocumentClick(event) {
-    if (!window.appticsReadyStatus || !isActive()) {
+    if (!window.appticsReadyStatus || !isActive() || !_ZAP._config.track_click) {
         return;
     }
     var start = event.target;
@@ -386,15 +623,16 @@ function onDocumentClick(event) {
     if (!start) {
         return;
     }
-    var targetElem = start.closest('[apeventaction]:not([apeventaction=""])'); // no i18n
+    var targetElem = start.closest(trackingSelector('apeventaction')); // no i18n
     if (!targetElem) {
         return;
     }
-    var eventName = targetElem.getAttribute('apeventaction') || ''; // no i18n
-    var groupElem = targetElem.closest('[apgroupaction]'); // no i18n
-    var groupName = (groupElem && groupElem.getAttribute('apgroupaction')) || AP_CONFIG.default_group_name; // no i18n
+    var eventName = trackingAttribute(targetElem, 'apeventaction') || ''; // no i18n
+    var groupElem = targetElem.closest(trackingSelector('apgroupaction')); // no i18n
+    // no apgroupaction around it: trackEvent refuses it and says the group is missing
+    var groupName = (groupElem && trackingAttribute(groupElem, 'apgroupaction')) || undefined; // no i18n
     var eventProps = {};
-    var rawProps = targetElem.getAttribute('apeventprops'); // no i18n
+    var rawProps = trackingAttribute(targetElem, 'apeventprops'); // no i18n
     if (!isEmpty(rawProps)) {
         try {
             eventProps = JSON.parse(rawProps);
@@ -416,10 +654,18 @@ function onDocumentClick(event) {
 function onPageHidden() {
     if (!isActive())
         return;
+    // the moment the user left: the session ends at it if they are not back within inactiveduration
+    markTabInactive(sendEndedSession);
     updateScreenWithEndtime();
     flush(true);
     Console.log('page hidden: closing the open screen and flushing'); // no i18n
 }
+/** A session that inactivity ended while the tab was away: sent now, not when the user returns. */
+function sendEndedSession() {
+    if (!isActive())
+        return;
+    flush();
+}
 /**
  * The tab is closing, or the page is being replaced or frozen into the back/forward cache.
  * The session ends here, and everything queued goes out by keepalive, since a normal
@@ -451,14 +697,18 @@ function attachListeners() {
     window.addEventListener('blur', function () {
         if (!isActive())
             return;
+        // focus moving into an iframe on the page blurs the window too, and the user is still here
+        if (document.activeElement && document.activeElement.tagName === 'IFRAME')
+            return; // no i18n
         Console.log('Window lost focus, user switched to another window or application'); // no i18n
-        updateLastActiveTimeOfSession();
+        markTabInactive(sendEndedSession);
     });
     // Track when the window gains focus (user switches back to the window)
     window.addEventListener('focus', function () {
         if (!isActive())
             return;
         Console.log('Window regained focus, user switched back to the window'); // no i18n
+        markTabActive();
         checkAndUpdateSession();
         startTimers();
     });
@@ -469,6 +719,7 @@ function attachListeners() {
         if (!isActive() || !event.persisted)
             return;
         Console.log('restored from the back/forward cache: starting a new session'); // no i18n
+        markTabActive();
         // the screen the page was left on starts a new view, in the new session
         checkAndUpdateSession().then(resumeScreen);
         startTimers();
@@ -480,12 +731,12 @@ function attachListeners() {
             onPageHidden();
             return;
         }
-        // back in view: the server's tracking flags may have changed while we were away
-        Console.log('page visible: refreshing the server settings'); // no i18n
+        // back in view. getsdkconfig is not asked here: only at its next_check_after, on a tab's
+        // first page load, and when a user is registered or getupdates reports a change
+        markTabActive();
         // hiding ended the screen view; the screen the user is back on starts a new one, after the
         // session is settled so the view belongs to the right one
         checkAndUpdateSession().then(resumeScreen);
-        refreshServerSettings();
     });
     // if we are running in cordova use ondeviceready otherwise onload
     window.addEventListener(window.cordova ? 'deviceready' : 'load', function () {
@@ -500,8 +751,8 @@ function attachListeners() {
         // until it has them: register before flushing, and flush once that has landed
         if (needsDevice()) {
             Console.log('back online: registering this device before sending'); // no i18n
-            checkAndUpdateDeviceInfo();
-            deviceReady().then(function () {
+            // the same locked path as start-up, so two tabs coming back online register it once
+            prepareDevice().then(deviceReady).then(function () {
                 if (!isActive())
                     return;
                 flush();
@@ -519,16 +770,26 @@ function attachListeners() {
         });
     }
     window.addEventListener('unhandledrejection', function (event) {
-        if (isActive() && _ZAP._isGlobalErrorTracking) {
+        if (isActive() && _ZAP._config.track_error) {
             trackError(event);
         }
     });
+    // in the capture phase: a <script>, <img> or <link> that fails to load fires `error` on the
+    // element, and it does not bubble, so a bubbling listener never hears of it. One listener
+    // hears both kinds, the window's own errors included, so none is counted twice
     window.addEventListener('error', function (event) {
-        if (isActive() && _ZAP._isGlobalErrorTracking) {
-            trackError(event);
+        if (!isActive() || !_ZAP._config.track_error) {
+            return;
         }
-    });
+        var target = event.target;
+        if (target && target !== window && typeof target.tagName === 'string') { // no i18n
+            // named by describeTarget: Event "error" on <script src="...">
+            trackError({ type: 'error', reason: event }); // no i18n
+            return;
+        }
+        trackError(event);
+    }, true);
     window.addEventListener('click', onDocumentClick, true); // no i18n
 }
 
-export { init, ready, reset };
+export { init, ready, reset, screenRouteRules, setClickTracking, setScreenTracking };