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

package/dist/esm/engagement/session.js

@@ -0,0 +1,448 @@
+/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta.1 | (c) Zoho Corporation Private Limited | see LICENSE */
+import { AP_CONSTANTS, AP_LOG_MODULE } from '../core/constants.js';
+import { _ZAP, getConfig } from '../core/state.js';
+import { logFailure, Console } from '../core/logger.js';
+import { isEmpty, getNewUUID, nowMs } from '../core/utils.js';
+import { engagement_transactions, getKeyFromDeviceInfo, setDeviceInfoKey } from '../core/storage.js';
+import { is_apptics_disabled, getNetworkStatus, getOrientation, getConnectionType, getRam } from '../core/env.js';
+import { canTrackEngagement } from '../core/consent.js';
+import { withLock } from '../core/locks.js';
+
+/** The most recently started item of `type` that is still open (endtime 0). */
+function latestOpen(type, items) {
+    return items.filter(function (item) {
+        return item.type == type && item.endtime === 0;
+    }).sort(function (a, b) {
+        return b.starttime - a.starttime;
+    })[0];
+}
+/**
+ * Ends one screen view, by id: it gets its end time and, with it, a duration, and becomes sendable
+ * (an open screen, endtime 0, waits like an open session does). A view already ended keeps its end.
+ */
+function closeScreen(id, time) {
+    if (isEmpty(id)) {
+        return Promise.resolve();
+    }
+    if (_ZAP._current_screen && _ZAP._current_screen.id === id && !_ZAP._current_screen.endtime) {
+        _ZAP._current_screen = Object.assign({}, _ZAP._current_screen, { endtime: time });
+    }
+    return engagement_transactions.all().then(function (items) {
+        var open = items.filter(function (item) {
+            return item.type == AP_CONSTANTS.SCREEN && item.id === id && item.endtime === 0;
+        })[0];
+        if (open) {
+            return engagement_transactions.update(Object.assign({}, open, { endtime: Math.max(time, open.starttime) }));
+        }
+    });
+}
+/**
+ * Ends this tab's current screen view: the page is hidden or closing. By id, so a screen another
+ * tab has open is never closed from here.
+ */
+function updateScreenWithEndtime() {
+    var current = _ZAP._current_screen;
+    return current && current.id ? closeScreen(current.id, nowMs()) : Promise.resolve();
+}
+/** Ends the screen views a session left open, at `time`: the session itself has ended. */
+function closeScreensOf(session, time) {
+    return engagement_transactions.all().then(function (items) {
+        var open = items.filter(function (item) {
+            return item.type == AP_CONSTANTS.SCREEN && item.endtime === 0 && item.sessionstarttime === session.starttime;
+        });
+        return open.reduce(function (done, item) {
+            return done.then(function () {
+                return engagement_transactions.update(Object.assign({}, item, { endtime: Math.max(time, item.starttime) }));
+            });
+        }, Promise.resolve());
+    });
+}
+/**
+ * Track the session.
+ * @param sessionData A set of properties belonging to the session.
+ */
+function trackSession(sessionData) {
+    if (!canTrackEngagement('trackSession')) { // no i18n
+        return Promise.resolve();
+    }
+    if (sessionData && typeof sessionData !== 'object') { // no i18n
+        logFailure(AP_LOG_MODULE.SESSION, 'apptics.trackSession: sessionData param must be an object'); // no i18n
+        return Promise.resolve();
+    }
+    var written = engagement_transactions.add(sessionData);
+    Console.log('apptics.trackSession(' + JSON.stringify(sessionData || {}) + ')'); // no i18n
+    Console.dir(sessionData);
+    return written;
+}
+/**
+ * This tab's session while it is open, otherwise the newest open session in storage: the one the
+ * site's other tabs are on, which this tab joins rather than starting a second session beside it.
+ */
+function currentSession() {
+    var mine = tabSessionId();
+    return engagement_transactions.all().then(function (items) {
+        if (mine) {
+            var ours = items.filter(function (item) {
+                return item.type == AP_CONSTANTS.SESSION && item.id === mine && item.endtime === 0;
+            })[0];
+            if (ours) {
+                return ours;
+            }
+        }
+        return latestOpen(AP_CONSTANTS.SESSION, items);
+    });
+}
+/**
+ * This page's own id, among the tabs sharing a session. New on every page load, so a reload or a
+ * duplicated tab counts as a tab of its own rather than as the one it came from. Made on first use,
+ * not when the module loads: getNewUUID reads `screen`, which a server-side render doesn't have.
+ */
+var tabIdValue = ''; // no i18n
+function tabId() {
+    if (tabIdValue === '') {
+        tabIdValue = getNewUUID();
+    }
+    return tabIdValue;
+}
+/**
+ * The tabs of this site using a session. All of them share one session, which ends when the last
+ * of them closes (see endCurrentSession). Kept on the stored session, never sent: see
+ * sendEngagementData. A session stored by an older SDK has none, and counts as this tab's alone.
+ */
+function tabsOf(session) {
+    return Array.isArray(session.tabs) ? session.tabs.slice() : [];
+}
+function withThisTab(session) {
+    var tabs = tabsOf(session);
+    if (tabs.indexOf(tabId()) === -1) {
+        tabs.push(tabId());
+    }
+    return tabs;
+}
+/* ---------------- screen views left open by tabs that are gone ----------------
+ * A screen view is ended by the tab that opened it: by the next screen, or as the page hides or
+ * closes. A tab that reloads, closes or crashes before that write lands leaves its view open, and
+ * nothing ended it until the whole session did, which with tabs sharing one session can be hours.
+ *
+ * So each tab holds a Web Lock, `apptics-tab-<its id>`, for as long as it is open: the browser
+ * lets go of it the moment the tab is gone, however it went. A tab that starts, or comes back into
+ * view, ends every open view whose tab no longer holds its lock, at the time that tab was last seen
+ * active. Without the Web Locks API, views are left as before and end with their session. */
+const TAB_LOCK_PREFIX = 'apptics-tab-'; // no i18n
+/** A view this young may belong to a tab whose lock is not granted yet: left alone. */
+const YOUNG_VIEW_MS = 5000;
+function tabLocks() {
+    var locks = typeof navigator !== 'undefined' ? navigator.locks : undefined; // no i18n
+    return locks && typeof locks.request === 'function' && typeof locks.query === 'function' ? locks : undefined; // no i18n
+}
+var holdingTabLock = false;
+/** Takes this tab's lock, held until the page is gone. Once per page. */
+function holdTabLock() {
+    var locks = tabLocks();
+    if (!locks || holdingTabLock) {
+        return;
+    }
+    holdingTabLock = true;
+    locks.request(TAB_LOCK_PREFIX + tabId(), function () {
+        return new Promise(function () { });
+    }).catch(function () {
+        holdingTabLock = false;
+    });
+}
+/** Ends the open screen views of tabs that are gone. Resolves right away without Web Locks. */
+function closeScreensOfGoneTabs() {
+    var locks = tabLocks();
+    if (!locks) {
+        return Promise.resolve();
+    }
+    var mine = tabId();
+    return locks.query().then(function (state) {
+        var alive = {};
+        (state.held || []).concat(state.pending || []).forEach(function (lock) {
+            if (lock.name && lock.name.indexOf(TAB_LOCK_PREFIX) === 0) {
+                alive[lock.name.slice(TAB_LOCK_PREFIX.length)] = true;
+            }
+        });
+        var now = nowMs();
+        return engagement_transactions.all().then(function (items) {
+            var gone = items.filter(function (item) {
+                return item.type == AP_CONSTANTS.SCREEN && item.endtime === 0 && typeof item.tab === 'string' // no i18n
+                    && item.tab !== mine && !alive[item.tab] && now - item.starttime > YOUNG_VIEW_MS;
+            });
+            if (gone.length) {
+                Console.log('closeScreensOfGoneTabs: ending ' + gone.length + ' screen view(s) left open by a tab that is gone'); // no i18n
+            }
+            return gone.reduce(function (done, item) {
+                // when that tab was last seen with the view open, not now: the time since is not time spent
+                var end = Math.max(item.starttime, Number(item.lastseen) || item.starttime);
+                return done.then(function () {
+                    return engagement_transactions.update(Object.assign({}, item, { endtime: end }));
+                });
+            }, Promise.resolve());
+        });
+    }).catch(function (err) {
+        Console.log('closeScreensOfGoneTabs: ' + err); // no i18n
+    });
+}
+/** Notes on this tab's open view that the tab is still here, the end a gone tab's view is given. */
+function markScreenSeen(time) {
+    var current = _ZAP._current_screen;
+    if (!current || !current.id || current.endtime) {
+        return Promise.resolve();
+    }
+    return engagement_transactions.all().then(function (items) {
+        var open = items.filter(function (item) {
+            return item.type == AP_CONSTANTS.SCREEN && item.id === current.id && item.endtime === 0;
+        })[0];
+        return open ? engagement_transactions.update(Object.assign({}, open, { lastseen: time })) : undefined;
+    });
+}
+/**
+ * Every change to the session runs under a lock shared by the site's tabs: each one reads the
+ * stored session, changes it and writes it back, and two tabs doing that at once would each write
+ * over the other's change.
+ */
+function withSessionLock(run) {
+    return withLock('session', run); // no i18n
+}
+/** The id of this tab's session. sessionStorage is per tab and survives a reload. */
+const TAB_KEY = 'apptics-session'; // no i18n
+function tabSessionId() {
+    try {
+        return sessionStorage.getItem(TAB_KEY) || ''; // no i18n
+    }
+    catch (err) {
+        return ''; // no sessionStorage (private mode, sandboxed frame): fall back to the store
+    }
+}
+function rememberTabSession(id) {
+    try {
+        sessionStorage.setItem(TAB_KEY, id);
+    }
+    catch (err) {
+        // the session still works, it just can't be recognised after a reload
+    }
+}
+/** True until the first session on this device has been recorded: device_info's hadsession. */
+function isFirstEverSession() {
+    return getKeyFromDeviceInfo(HAD_SESSION_KEY) !== true;
+}
+const HAD_SESSION_KEY = 'hadsession'; // no i18n
+/**
+ * A session that has begun but is not stored yet.
+ *
+ * A visit shorter than `min_session_duration` and with nothing tracked in it is not a session worth
+ * reporting — a bounce, a preview, a crawler that runs scripts. So the session is held here for
+ * those first seconds and written only once it has earned it: when the timer fires, or the moment
+ * anything is tracked that needs a session to belong to, whichever comes first.
+ *
+ * `_ZAP._current_session` is set as soon as the session begins even though this is pending, so
+ * anything tracked in those seconds still reads the right `sessionstarttime`. Committing does not
+ * change `starttime`: it stays the moment the session began, so the wait is never counted as a gap.
+ */
+var pendingSession = null;
+var pendingTimer = null;
+function clearPendingTimer() {
+    if (pendingTimer !== null) {
+        clearTimeout(pendingTimer);
+        pendingTimer = null;
+    }
+}
+/**
+ * Writes the waiting session, if there is one. Called by the timer and by anything that tracks an
+ * item, so an event in the first seconds takes its session with it.
+ */
+function commitPendingSession() {
+    if (!pendingSession) {
+        return Promise.resolve();
+    }
+    var session = pendingSession;
+    pendingSession = null;
+    clearPendingTimer();
+    // the flag is set here rather than at the start, so a dropped session does not consume it and
+    // leave the next real session reporting firstsession false
+    if (session.firstsession) {
+        setDeviceInfoKey(HAD_SESSION_KEY, true);
+    }
+    return trackSession(session);
+}
+/** Forgets a session that never earned its place, on a tab closing inside the minimum. */
+function dropPendingSession() {
+    if (!pendingSession) {
+        return false;
+    }
+    Console.log('session: dropped, shorter than the minimum with nothing tracked in it'); // no i18n
+    pendingSession = null;
+    clearPendingTimer();
+    return true;
+}
+function startNewSession(time) {
+    _ZAP._current_session = {
+        id: getNewUUID(),
+        type: AP_CONSTANTS.SESSION,
+        starttime: time,
+        endtime: 0,
+        edge: getConnectionType(),
+        orientation: getOrientation(),
+        firstsession: isFirstEverSession(),
+        networkstatus: getNetworkStatus(),
+        lastactivetime: time,
+        tabs: [tabId()],
+    };
+    // ram is optional in sessionWebSDK but checked against ram_rom ('4 GB'), which an empty
+    // string cannot match. navigator.deviceMemory is Chromium-only, so Firefox and Safari have
+    // nothing to put here - and a key that fails its regex does not lose the session, it loses
+    // the whole batch the session was sent in, permanently
+    var ram = getRam();
+    if (!isEmpty(ram)) {
+        _ZAP._current_session.ram = ram;
+    }
+    rememberTabSession(_ZAP._current_session.id);
+    var minimum = Number(getConfig('min_session_duration'));
+    if (!(minimum > 0)) {
+        return commitNow(_ZAP._current_session);
+    }
+    // held, not stored: see pendingSession above
+    pendingSession = _ZAP._current_session;
+    clearPendingTimer();
+    pendingTimer = setTimeout(function () {
+        pendingTimer = null;
+        commitPendingSession();
+    }, minimum);
+    return Promise.resolve();
+}
+/** The un-deferred path, for a minimum of 0. */
+function commitNow(session) {
+    if (session.firstsession) {
+        setDeviceInfoKey(HAD_SESSION_KEY, true);
+    }
+    return trackSession(session);
+}
+/**
+ * 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.
+ */
+function endCurrentSession() {
+    var time = nowMs();
+    // 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);
+    });
+}
+function closeOrLeaveSession(time) {
+    return currentSession().then(function (_currentSession) {
+        if (!_currentSession || _currentSession.endtime !== 0) {
+            return;
+        }
+        var others = tabsOf(_currentSession).filter(function (tab) { return tab !== tabId(); });
+        if (others.length > 0) {
+            var left = Object.assign({}, _currentSession, { tabs: others, lastactivetime: time });
+            _ZAP._current_session = left;
+            Console.log('endCurrentSession: ' + others.length + ' other tab(s) still on this session, so it stays open'); // no i18n
+            return engagement_transactions.update(left);
+        }
+        var closed = Object.assign({}, _currentSession, { endtime: time, lastactivetime: time, tabs: [] });
+        _ZAP._current_session = closed;
+        Console.log('endCurrentSession: closing the session opened at ' + closed.starttime); // no i18n
+        return engagement_transactions.update(closed).then(function () {
+            return closeScreensOf(closed, time);
+        });
+    });
+}
+/**
+ * Closes sessions left open by a tab that was killed before it could close its own: anything
+ * idle for longer than inactiveduration. A live tab in another window keeps its session,
+ * because that one's lastactivetime is recent.
+ */
+function closeAbandonedSessions() {
+    var cutoff = nowMs() - _ZAP.inactiveduration * 60 * 1000;
+    var mine = tabSessionId();
+    return engagement_transactions.all().then(function (items) {
+        var abandoned = items.filter(function (item) {
+            return item.type == AP_CONSTANTS.SESSION && item.endtime === 0 &&
+                item.id !== mine && item.lastactivetime < cutoff;
+        });
+        if (!abandoned.length) {
+            return Promise.resolve();
+        }
+        Console.log('closeAbandonedSessions: closing ' + abandoned.length + ' session(s) left open by a closed tab'); // no i18n
+        return abandoned.reduce(function (done, item) {
+            return done.then(function () {
+                return engagement_transactions.update(Object.assign({}, item, { endtime: item.lastactivetime }));
+            }).then(function () {
+                // the screen the closed tab was on ends with its session
+                return closeScreensOf(item, item.lastactivetime);
+            });
+        }, Promise.resolve());
+    });
+}
+function checkAndUpdateSession() {
+    if (!_ZAP._token) {
+        logFailure(AP_LOG_MODULE.SESSION, 'checkAndUpdateSession: You must call Apptics.init() first'); // no i18n
+        return Promise.resolve();
+    }
+    if (is_apptics_disabled()) {
+        return Promise.resolve();
+    }
+    var time = nowMs();
+    return withSessionLock(function () {
+        return settleSession(time);
+    });
+}
+function settleSession(time) {
+    // a tab that was killed before it could close its session: close it so it gets sent; and the
+    // screen views left open by tabs that are gone, so they end now rather than with the session
+    return closeAbandonedSessions().then(closeScreensOfGoneTabs).then(currentSession).then(function (_currentSession) {
+        // a closed session belongs to a tab that has gone: this tab starts its own
+        if (!_currentSession || _currentSession.endtime !== 0) {
+            return startNewSession(time);
+        }
+        _ZAP._current_session = _currentSession;
+        // Check if the user is inactive for the past 30 minutes
+        if ((time - _currentSession.lastactivetime) > (_ZAP.inactiveduration * 1000 * 60)) {
+            Console.log('checkAndUpdateSession: User is inactive for the past ' + _ZAP.inactiveduration + ' minutes so starting a new session'); // no i18n
+            // ends when the user was last active, so the idle gap isn't counted as session time
+            var _newSession = Object.assign({}, _currentSession, { endtime: _currentSession.lastactivetime });
+            Console.log('checkAndUpdateSession: (' + JSON.stringify(_newSession) + ')'); // no i18n
+            Console.dir(_newSession);
+            return engagement_transactions.update(_newSession).then(function () {
+                // the screen left open over the idle gap ends with the session, when it was last used
+                return closeScreensOf(_newSession, _newSession.endtime);
+            }).then(function () {
+                return startNewSession(time);
+            });
+        }
+        Console.log('checkAndUpdateSession: User is back before ' + _ZAP.inactiveduration + ' minutes so updating the lastactivitytime - ' + time); // no i18n
+        return touchSession();
+    });
+}
+function updateLastActiveTimeOfSession() {
+    return withSessionLock(touchSession);
+}
+/** Marks the session active now, with this tab among its tabs. Callers hold the session lock. */
+function touchSession() {
+    var time = nowMs();
+    // a pending session is not in the store yet, so it is updated in place instead
+    if (pendingSession) {
+        pendingSession.lastactivetime = time;
+        _ZAP._current_session = pendingSession;
+        return Promise.resolve();
+    }
+    return currentSession().then(function (_currentSession) {
+        if (!_currentSession) {
+            return;
+        }
+        Console.log('updateLastActiveTimeOfSession: Updating the lastactivitytime - ' + time); // no i18n
+        var _newSession = Object.assign({}, _currentSession, { lastactivetime: time, tabs: withThisTab(_currentSession) });
+        _ZAP._current_session = _newSession;
+        return engagement_transactions.update(_newSession);
+    }).then(function () {
+        return markScreenSeen(time);
+    });
+}
+
+export { checkAndUpdateSession, closeAbandonedSessions, closeScreen, closeScreensOfGoneTabs, commitPendingSession, currentSession, dropPendingSession, endCurrentSession, holdTabLock, startNewSession, tabId, trackSession, updateLastActiveTimeOfSession, updateScreenWithEndtime };

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

@@ -0,0 +1,56 @@
+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
+ * `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`.
+ */
+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. */
+export declare function inScreen(screenName: string, jsonObj?: Properties): string;
+/**
+ * The app's own screen view with a known id and start. The public inScreen takes the id and the
+ * time when the app calls it, so the id it hands back is the view's even when start-up is still
+ * running and this runs a moment later.
+ */
+export declare function inScreenAt(screenName: string, jsonObj: Properties | undefined, id: string, startedAt: number): void;
+/** Ends the screen view inScreen() began, as Android's AppticsScreenTracker.outScreen(id). */
+export declare function outScreenAt(id: string, endedAt: number): void;
+/**
+ * Queues a screen view and makes it the current screen.
+ *
+ * The view is stored open (endtime 0) and closed when the next screen starts, when the page is
+ * hidden or closed, when its session ends, or by outScreen() — which is what gives it a duration.
+ * An open view is not sent until it is closed, as an open session is not.
+ */
+export declare function recordScreen(screenName: string, jsonObj?: Properties, id?: string, startedAt?: number, implicit?: boolean): void;
+/**
+ * The screen a heatmap record belongs to, making sure engagement/add has a view of it: the console
+ * places a record by its screen, and a screen that was never sent as a view leaves it nowhere.
+ *
+ * A screen the app or automatic screen tracking named is used as it is — that one already has its
+ * view. Otherwise (automatic tracking off and no inScreen() call) the page is named the way
+ * automatic tracking would name it, and a view is recorded for it: once per screen, a new one when
+ * the path changes, and given way as soon as anything else names the screen.
+ */
+export declare function screenForRecord(): string;
+/**
+ * Back in view after being hidden: the hide ended the screen view, so the screen the user is on
+ * starts a new one, as an Android activity coming back to the foreground does.
+ */
+export declare function resumeScreen(): void;
+export declare function trackApi(jsonObj?: Dict): void;
+/**
+ * Begins timing one API call, as Android's AppticsApiTracker.startTrackApi(url, method): returns
+ * the id to hand to endTrackApi once the response is in. Records nothing by itself.
+ */
+export declare function startTrackApi(url: string, method?: string): string;
+/**
+ * Finishes a call startTrackApi began and records it, timed from start to `endedAt`. The public
+ * wrapper takes `endedAt` when the app calls it, so a call ended while start-up is still running
+ * keeps its real duration even though it is recorded a moment later.
+ */
+export declare function endTrackApiAt(id: string, responseCode: number, responseMessage: string | undefined, endedAt: number): void;