@zoho_apptics/apptics-js-sdk 1.0.1 → 2.0.0-beta

package/dist/esm/engagement/session.js

@@ -0,0 +1,315 @@
+/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta | (c) Zoho Corporation Private Limited | see LICENSE */
+import { AP_LOG_MODULE, AP_CONSTANTS } from '../core/constants.js';
+import { _ZAP, getConfig } from '../core/state.js';
+import { logFailure, Console } from '../core/logger.js';
+import { nowMs, isEmpty, getNewUUID } from '../core/utils.js';
+import { engagement_transactions, user_defaults } from '../core/storage.js';
+import { is_apptics_disabled, getNetworkStatus, getOrientation, getConnectionType, getRam } from '../core/env.js';
+import { canTrackEngagement } from '../core/consent.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_session: false`, Android's automaticSessionsTrackingStatus: no sessions are recorded. */
+function sessionsOff() {
+    return getConfig('track_session') === false; // no i18n
+}
+/**
+ * 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 when it has one, otherwise the newest open session in storage. */
+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;
+            })[0];
+            if (ours) {
+                return ours;
+            }
+        }
+        return latestOpen(AP_CONSTANTS.SESSION, items);
+    });
+}
+/** 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. */
+function isFirstEverSession() {
+    return isEmpty(user_defaults.item(HAD_SESSION_KEY));
+}
+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) {
+        user_defaults.add(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,
+    };
+    // 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) {
+        user_defaults.add(HAD_SESSION_KEY, true);
+    }
+    return trackSession(session);
+}
+/**
+ * Closes this tab's session, so it can be sent: the tab is closing or the page is being replaced.
+ * Nothing happens when the session 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 currentSession().then(function (_currentSession) {
+        if (!_currentSession || _currentSession.endtime !== 0) {
+            return;
+        }
+        var closed = Object.assign({}, _currentSession, { endtime: time, lastactivetime: time });
+        _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();
+    }
+    if (sessionsOff()) {
+        return Promise.resolve();
+    }
+    var time = nowMs();
+    // a tab that was killed before it could close its session: close it so it gets sent
+    return closeAbandonedSessions().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 updateLastActiveTimeOfSession();
+    });
+}
+function updateLastActiveTimeOfSession() {
+    if (sessionsOff()) {
+        return Promise.resolve();
+    }
+    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 });
+        _ZAP._current_session = _newSession;
+        return engagement_transactions.update(_newSession);
+    });
+}
+
+export { checkAndUpdateSession, closeAbandonedSessions, closeScreen, commitPendingSession, currentSession, dropPendingSession, endCurrentSession, startNewSession, 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;