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

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

@@ -0,0 +1,198 @@
+/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta | (c) Zoho Corporation Private Limited | see LICENSE */
+import { _ZAP, getConfig } from '../core/state.js';
+import { Console } from '../core/logger.js';
+import { nowMs, isEmpty } from '../core/utils.js';
+import { trackApi } from './track.js';
+import { hostAllowed, endpointIgnored } from './api-rules.js';
+
+/**
+ * Automatic API tracking: wraps XMLHttpRequest and fetch so calls the app makes are recorded
+ * without it calling startTrackApi() / endTrackApi() itself.
+ *
+ * Two rules shape everything here. The wrappers must be invisible — return values, `this`, thrown
+ * errors and argument forms all pass straight through, because a mistake in this file breaks the
+ * host app's networking rather than just losing a metric. And the SDK's own traffic must never be
+ * recorded: engagement/add reports API calls, so tracking it would have each batch produce the
+ * items for the next one.
+ *
+ * Off unless `track_api` is set. Hostnames and paths of every request an app makes is a wider
+ * grant than events and screens, so it is the app's decision, not a default.
+ */
+var installed = false;
+var originalOpen = null;
+var originalSend = null;
+var originalFetch = null;
+/**
+ * Whether a request is the SDK's own, which is never reported: engagement/add carries API items, so
+ * recording it would have every batch produce the items for the next one, forever.
+ *
+ * Two checks, because one is not enough to bet a loop on. The host comparison is a prefix match, so
+ * it misses if the host is spelled differently in the request than in serviceUrl — a trailing
+ * slash is enough. The path check catches those, since every SDK call sits under the configured
+ * endpoint whatever host it goes to, including through a same-origin proxy.
+ */
+function isOwnRequest(url, pathname) {
+    var own = [_ZAP._defaultoptions.base_domain, _ZAP._defaultoptions.serviceUrl];
+    for (var i = 0; i < own.length; i++) {
+        if (!isEmpty(own[i]) && url.indexOf(own[i]) === 0) {
+            return true;
+        }
+    }
+    var endpoint = getConfig('endpoint');
+    return !isEmpty(endpoint) && pathname.indexOf(endpoint) === 0;
+}
+/**
+ * Whether one URL is ours to report: an http(s) call, not the SDK's own, and one the
+ * configureApiTracking rules let through. Anything unparseable is skipped rather than guessed at.
+ */
+function shouldTrack(rawUrl) {
+    if (isEmpty(rawUrl)) {
+        return false;
+    }
+    var absolute;
+    try {
+        absolute = new URL(rawUrl, window.location.href);
+    }
+    catch (err) {
+        return false;
+    }
+    if (absolute.protocol !== 'https:' && absolute.protocol !== 'http:') { // no i18n
+        return false; // data:, blob:, chrome-extension: and friends
+    }
+    if (isOwnRequest(absolute.href, absolute.pathname)) {
+        return false;
+    }
+    // configureApiTracking's rules: checked here too so a call left out is not even timed. trackApi checks them again, for the
+    // calls an app reports itself
+    return hostAllowed(absolute.hostname) && !endpointIgnored(absolute.pathname);
+}
+/** One finished call. Never throws: a tracking failure must not surface in the app's call. */
+function record(method, url, starttime, responsecode, responsemessage) {
+    try {
+        trackApi({
+            url: url,
+            method: method,
+            responsecode: responsecode,
+            responsemessage: responsemessage,
+            starttime: starttime,
+            endtime: nowMs(),
+        });
+    }
+    catch (err) {
+        Console.log('auto api tracking: ' + String(err)); // no i18n
+    }
+}
+/** The url of any of fetch's three first-argument forms. */
+function fetchUrl(input) {
+    if (typeof input === 'string') { // no i18n
+        return input;
+    }
+    if (typeof Request !== 'undefined' && input instanceof Request) { // no i18n
+        return input.url;
+    }
+    return String(input);
+}
+function fetchMethod(input, init) {
+    if (init && init.method) {
+        return init.method;
+    }
+    if (typeof Request !== 'undefined' && input instanceof Request) { // no i18n
+        return input.method;
+    }
+    return 'GET'; // no i18n
+}
+function installXhr() {
+    if (typeof XMLHttpRequest !== 'function') { // no i18n
+        return;
+    }
+    originalOpen = XMLHttpRequest.prototype.open;
+    originalSend = XMLHttpRequest.prototype.send;
+    XMLHttpRequest.prototype.open = function (method, url) {
+        try {
+            var href = String(url);
+            if (shouldTrack(href)) {
+                // starttime is set in send(): open() may happen long before the call goes out
+                this._ap_api = { method: String(method || 'GET'), url: href, starttime: 0 }; // no i18n
+            }
+            else {
+                this._ap_api = undefined;
+            }
+        }
+        catch (err) {
+            this._ap_api = undefined;
+        }
+        return originalOpen.apply(this, arguments);
+    };
+    XMLHttpRequest.prototype.send = function () {
+        const tracked = this._ap_api;
+        if (tracked) {
+            tracked.starttime = nowMs();
+            // loadend fires for success, error, abort and timeout alike, so one listener covers
+            // every ending; status 0 is how a network failure arrives here
+            this.addEventListener('loadend', function () {
+                var message = this.status === 0 ? 'Network Error' : (this.statusText || '-'); // no i18n
+                record(tracked.method, tracked.url, tracked.starttime, this.status, message);
+            });
+        }
+        return originalSend.apply(this, arguments);
+    };
+}
+function installFetch() {
+    if (typeof fetch !== 'function') { // no i18n
+        return;
+    }
+    originalFetch = fetch;
+    window.fetch = function (input, init) {
+        var url, method, starttime;
+        try {
+            url = fetchUrl(input);
+            method = fetchMethod(input, init);
+            starttime = nowMs();
+        }
+        catch (err) {
+            return originalFetch(input, init);
+        }
+        if (!shouldTrack(url)) {
+            return originalFetch(input, init);
+        }
+        return originalFetch(input, init).then(function (response) {
+            record(method, url, starttime, response.status, response.statusText || '-'); // no i18n
+            return response;
+        }, function (err) {
+            // a rejected fetch never reached a status; the rejection is re-thrown untouched
+            record(method, url, starttime, 0, String(err && err.message ? err.message : err) || 'Network Error'); // no i18n
+            throw err;
+        });
+    };
+}
+/**
+ * Starts or stops automatic tracking. Safe to call repeatedly: installing twice would report each
+ * call twice, so the second call is a no-op.
+ */
+function enableApiTracking(enabled) {
+    var on = typeof enabled === 'boolean' ? enabled : true; // no i18n
+    if (on === installed) {
+        return;
+    }
+    if (on) {
+        installXhr();
+        installFetch();
+        installed = true;
+        Console.log('automatic api tracking: on'); // no i18n
+        return;
+    }
+    if (originalOpen) {
+        XMLHttpRequest.prototype.open = originalOpen;
+    }
+    if (originalSend) {
+        XMLHttpRequest.prototype.send = originalSend;
+    }
+    if (originalFetch) {
+        window.fetch = originalFetch;
+    }
+    originalOpen = originalSend = originalFetch = null;
+    installed = false;
+    Console.log('automatic api tracking: off'); // no i18n
+}
+
+export { enableApiTracking };

package/dist/esm/engagement/auto-screen.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Starts or stops automatic screen tracking. Starting records the screen the page is on, unless
+ * the app has already called inScreen() for it. Safe to call repeatedly: wrapping history twice
+ * would check every navigation twice, so a second start does nothing. `wait` replaces SETTLE_MS,
+ * for tests.
+ */
+export declare function enableScreenTracking(enabled?: boolean, wait?: number): void;
+/**
+ * The name automatic tracking gives the page as it is now: the cleaned path. For records that
+ * need a screen when none has been
+ * tracked — heatmaps with `track_screen: false` and no inScreen() call, say. '' when the page
+ * has no name.
+ */
+export declare function automaticScreenName(): string;
+/** Whether history is being watched right now. */
+export declare function isScreenTrackingEnabled(): boolean;

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

@@ -0,0 +1,238 @@
+/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta | (c) Zoho Corporation Private Limited | see LICENSE */
+import { Console } from '../core/logger.js';
+import { hooks } from '../core/hooks.js';
+import { _ZAP } from '../core/state.js';
+import { nowMs } from '../core/utils.js';
+import { recordScreen } from './track.js';
+
+/**
+ * Automatic screen tracking: a screen view for the page the SDK starts on, and one for every
+ * navigation after, without the app calling inScreen() from its router.
+ *
+ * Single-page routers move with history.pushState and replaceState, which fire no event, so those
+ * two are wrapped; back and forward arrive as popstate, and hash routers as hashchange. As with
+ * automatic API tracking, the wrappers must be invisible — arguments, `this` and the return value
+ * pass straight through — because a mistake here breaks the app's navigation, not just a metric.
+ *
+ * A router seldom makes one history call per move: it pushes the route, then replaces it to store
+ * its own state. Calls are therefore collected into one check a tick later, and a name equal to
+ * the last one recorded is not a new view. That also keeps a replaceState that only stores state
+ * from counting as a screen.
+ *
+ * An app may still name some screens itself. A inScreen() call during a navigation replaces
+ * the automatic view of it, so the navigation counts once, under the app's name. Router hooks
+ * often run after the navigation has been seen — React's effects, a Vue afterEach — so the
+ * automatic view waits SETTLE_MS before it is recorded, and a manual call in that time wins. The
+ * new path is the current screen from the moment the navigation is seen, so events fired while
+ * the page mounts are attributed to it, not to the page that was left. A page left again within
+ * the wait, such as a redirect, is not counted.
+ *
+ * On by default: most apps never call inScreen() themselves, and a screen-less session says
+ * little. An app that wants only its own calls sets `track_screen: false`.
+ */
+/** The most a screen name may be, and the characters it may hold (see validateScreenName). */
+const NAME_MAX = 99;
+const NAME_DISALLOWED = /[^\w\s.\-&/:]/g;
+/** How long an automatic view waits for the app's own inScreen() of the same navigation. */
+const SETTLE_MS = 300;
+var installed = false;
+/** The name last recorded, so a navigation that lands on the same screen is not a new view. */
+var lastName = ''; // no i18n
+var timer = null;
+var settleMs = SETTLE_MS;
+/** The automatic view waiting out SETTLE_MS, and its timer. */
+var pendingName = ''; // no i18n
+var settleTimer = null;
+/** The app called inScreen() during the current navigation, so it is not recorded here. */
+var claimed = false;
+/** When the navigation waiting out SETTLE_MS happened: its view starts then, not when recorded. */
+var pendingAt = 0;
+/** The wrappers this module put on history, to tell them apart from one a library added later. */
+var wrappedPush = null;
+var wrappedReplace = null;
+var originalPush = null;
+var originalReplace = null;
+/**
+ * The default name: the path, without the query string, which is where search terms, tokens and
+ * other values that are not a screen live. A hash route (`#/orders`, `#!/orders`) is the route,
+ * so it is joined onto the path; a plain `#anchor` is a place on the same screen and is left out.
+ */
+function nameFromUrl(url) {
+    var path = url.pathname;
+    var hash = url.hash;
+    if (/^#!?\//.test(hash)) {
+        var route = hash.replace(/^#!?/, '').split('?')[0]; // no i18n
+        path = path.replace(/\/+$/, '') + route; // no i18n
+    }
+    return path;
+}
+/**
+ * A name inScreen will accept. A path holds characters a screen name may not — percent
+ * encoding, `+`, `@` — and a refused name is dropped, so they are replaced rather than risked.
+ */
+function cleanName(raw) {
+    var name = raw;
+    try {
+        name = decodeURIComponent(raw);
+    }
+    catch (err) {
+        // a malformed escape: clean it as it stands
+    }
+    return name.replace(NAME_DISALLOWED, '_').trim().slice(0, NAME_MAX); // no i18n
+}
+/**
+ * The name for the page as it is now, from its url, or '' to record nothing. Never throws. An app
+ * that wants its own names calls inScreen() as the route changes, which replaces this view.
+ */
+function currentName() {
+    try {
+        return cleanName(nameFromUrl(new URL(window.location.href)));
+    }
+    catch (err) {
+        return ''; // no i18n
+    }
+}
+function check() {
+    timer = null;
+    if (!installed) {
+        return;
+    }
+    var name = currentName();
+    if (name === '' || name === lastName) { // no i18n
+        return;
+    }
+    lastName = name;
+    if (claimed) {
+        return; // the app has already recorded this navigation under its own name
+    }
+    // the current screen now, the view once SETTLE_MS has passed with no inScreen() of the app's.
+    // The open view keeps its id, so the view that follows still closes it, at the navigation
+    _ZAP._current_screen = Object.assign({}, _ZAP._current_screen, { screen: name });
+    pendingName = name;
+    pendingAt = nowMs();
+    settleTimer = setTimeout(settle, settleMs);
+}
+function settle() {
+    settleTimer = null;
+    var name = pendingName;
+    pendingName = ''; // no i18n
+    if (!installed || claimed || name === '') { // no i18n
+        return;
+    }
+    try {
+        recordScreen(name, undefined, undefined, pendingAt || undefined);
+    }
+    catch (err) {
+        Console.log('automatic screen tracking: ' + String(err)); // no i18n
+    }
+}
+/** Drops an automatic view still waiting out SETTLE_MS. */
+function cancelPending() {
+    if (settleTimer !== null) {
+        clearTimeout(settleTimer);
+        settleTimer = null;
+    }
+    pendingName = ''; // no i18n
+}
+/**
+ * Collects the history calls and events of one navigation into a single check. The first call of
+ * a navigation starts it afresh: a inScreen() from before it belonged to the previous screen,
+ * and a view still waiting is a page left too soon to count.
+ */
+function navigated() {
+    if (timer === null) {
+        claimed = false;
+        cancelPending();
+        timer = setTimeout(check, 0);
+    }
+}
+/** The app recorded a screen itself; the automatic view of this navigation gives way to it. */
+function screenTrackedByApp() {
+    claimed = true;
+    cancelPending();
+}
+function installHistory() {
+    var push = history.pushState;
+    var replace = history.replaceState;
+    originalPush = push;
+    originalReplace = replace;
+    wrappedPush = function () {
+        var result = push.apply(this, arguments);
+        navigated();
+        return result;
+    };
+    wrappedReplace = function () {
+        var result = replace.apply(this, arguments);
+        navigated();
+        return result;
+    };
+    history.pushState = wrappedPush;
+    history.replaceState = wrappedReplace;
+}
+/**
+ * Puts history back. Only a wrapper still on top is taken off: if a library wrapped history after
+ * us, removing ours would remove theirs too. Ours then stays inside theirs, passing calls through
+ * and recording nothing, since `installed` is false.
+ */
+function restoreHistory() {
+    if (wrappedPush && history.pushState === wrappedPush && originalPush) {
+        history.pushState = originalPush;
+    }
+    if (wrappedReplace && history.replaceState === wrappedReplace && originalReplace) {
+        history.replaceState = originalReplace;
+    }
+    wrappedPush = wrappedReplace = originalPush = originalReplace = null;
+}
+/**
+ * Starts or stops automatic screen tracking. Starting records the screen the page is on, unless
+ * the app has already called inScreen() for it. Safe to call repeatedly: wrapping history twice
+ * would check every navigation twice, so a second start does nothing. `wait` replaces SETTLE_MS,
+ * for tests.
+ */
+function enableScreenTracking(enabled, wait) {
+    var on = typeof enabled === 'boolean' ? enabled : true; // no i18n
+    if (on) {
+        settleMs = SETTLE_MS; // no i18n
+    }
+    if (on === installed) {
+        return;
+    }
+    if (on) {
+        lastName = ''; // no i18n
+        installHistory();
+        window.addEventListener('popstate', navigated); // no i18n
+        window.addEventListener('hashchange', navigated); // no i18n
+        installed = true;
+        Console.log('automatic screen tracking: on'); // no i18n
+        // the page the SDK starts on. Not through navigated(): a inScreen() the app made during
+        // start-up was replayed just before this, and it is this screen's, so its claim stands
+        if (timer === null) {
+            timer = setTimeout(check, 0);
+        }
+        return;
+    }
+    restoreHistory();
+    window.removeEventListener('popstate', navigated); // no i18n
+    window.removeEventListener('hashchange', navigated); // no i18n
+    if (timer !== null) {
+        clearTimeout(timer);
+        timer = null;
+    }
+    cancelPending();
+    installed = false;
+    lastName = ''; // no i18n
+    claimed = false;
+    Console.log('automatic screen tracking: off'); // no i18n
+}
+/**
+ * The name automatic tracking gives the page as it is now: the cleaned path. For records that
+ * need a screen when none has been
+ * tracked — heatmaps with `track_screen: false` and no inScreen() call, say. '' when the page
+ * has no name.
+ */
+function automaticScreenName() {
+    return currentName();
+}
+hooks.screenTrackedByApp = screenTrackedByApp;
+
+export { automaticScreenName, enableScreenTracking };

package/dist/esm/engagement/defined-events.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Apptics' defined events, as Android's DefinedEvents: ready-made names in reserved `AP_` groups,
+ * logged with trackEvent like any other event and never tracked automatically.
+ *
+ *   trackEvent(DefinedEvents.AP_USER_LOGIN);
+ *   trackEvent(DefinedEvents.AP_SEARCH, { query_length: 12 });
+ *
+ * They are the only events allowed the `ap_` prefix: an app's own event, group or property may
+ * not start with it. The list is Android's, so the console reads them the same from every platform;
+ * some (battery, OS update, uninstall) have no meaning in a browser and are simply never sent.
+ */
+/** One defined event: the name and the group it is sent under. */
+export interface DefinedEvent {
+    readonly event: string;
+    readonly group: string;
+}
+/** Every defined event, by name: `DefinedEvents.AP_USER_LOGIN` and so on. */
+export declare const DefinedEvents: Readonly<Record<string, DefinedEvent>>;
+/**
+ * The defined event `value` is, or undefined. Only the entries of DefinedEvents count, compared by
+ * identity, so an object that merely looks like one cannot borrow the reserved prefix.
+ */
+export declare function asDefinedEvent(value: unknown): DefinedEvent | undefined;

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

@@ -0,0 +1,55 @@
+/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta | (c) Zoho Corporation Private Limited | see LICENSE */
+/**
+ * Apptics' defined events, as Android's DefinedEvents: ready-made names in reserved `AP_` groups,
+ * logged with trackEvent like any other event and never tracked automatically.
+ *
+ *   trackEvent(DefinedEvents.AP_USER_LOGIN);
+ *   trackEvent(DefinedEvents.AP_SEARCH, { query_length: 12 });
+ *
+ * They are the only events allowed the `ap_` prefix: an app's own event, group or property may
+ * not start with it. The list is Android's, so the console reads them the same from every platform;
+ * some (battery, OS update, uninstall) have no meaning in a browser and are simply never sent.
+ */
+const GROUPS = {
+    AP_APP_LIFE_CYCLE: [
+        'AP_APP_INSTALL', 'AP_APP_UNINSTALL', 'AP_APP_UPDATE', 'AP_APP_CRACKED', 'AP_APP_OPEN', 'AP_APP_CLEAR_DATA', // no i18n
+        'AP_APP_FOREGROUND', 'AP_APP_BACKGROUND', 'AP_APP_OUT_OF_MEMORY', 'AP_APP_FIRST_OPEN', 'AP_APP_LAUNCHING', // no i18n
+        'AP_APP_RESIGN_ACTIVE', 'AP_APP_WILL_CONNECT', // no i18n
+    ],
+    AP_USER_LIFE_CYCLE: ['AP_USER_SIGNUP', 'AP_USER_LOGIN', 'AP_USER_LOGOUT'], // no i18n
+    AP_APPLICATION: [
+        'AP_DEEP_LINK_OPEN', 'AP_DEEP_LINK_UPDATE', 'AP_DEEP_LINK_FIRST_OPEN', 'AP_IN_APP_PURCHASE', // no i18n
+        'AP_NOTIFICATION_RECEIVE', 'AP_NOTIFICATION_OPEN', 'AP_NOTIFICATION_DISMISS', 'AP_NOTIFICATION_FOREGROUND', // no i18n
+        'AP_SEARCH', 'AP_BATTERY_LOW', 'AP_BATTERY_FULL', 'AP_LOW_POWER_MODE_ON', 'AP_LOW_POWER_MODE_OFF', // no i18n
+    ],
+    AP_OTHERS: [
+        'AP_NETWORK_REACHABILITY_CHANGE', 'AP_NETWORK_BANDWIDTH_CHANGE', 'AP_SWITCH_THEME_LIGHT', // no i18n
+        'AP_SWITCH_THEME_DARK', 'AP_SWITCH_THEME_CUSTOM', 'AP_SWITCH_ORIENTATION_LANDSCAPE', // no i18n
+        'AP_SWITCH_ORIENTATION_PORTRAIT', // no i18n
+    ],
+    AP_OS: ['AP_OS_UPDATE', 'AP_OS_UNSUPPORTED'], // no i18n
+};
+function build() {
+    var out = {};
+    Object.keys(GROUPS).forEach(function (group) {
+        GROUPS[group].forEach(function (event) {
+            out[event] = Object.freeze({ event: event, group: group });
+        });
+    });
+    return Object.freeze(out);
+}
+/** Every defined event, by name: `DefinedEvents.AP_USER_LOGIN` and so on. */
+const DefinedEvents = build();
+/**
+ * The defined event `value` is, or undefined. Only the entries of DefinedEvents count, compared by
+ * identity, so an object that merely looks like one cannot borrow the reserved prefix.
+ */
+function asDefinedEvent(value) {
+    if (!value || typeof value !== 'object') { // no i18n
+        return undefined;
+    }
+    var named = value.event;
+    return typeof named === 'string' && DefinedEvents[named] === value ? value : undefined; // no i18n
+}
+
+export { DefinedEvents, asDefinedEvent };

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

@@ -0,0 +1,6 @@
+import type { Dict, ServerResult } from '../types.js';
+/**
+ * Sends pending engagements to the Apptics API.
+ */
+export declare function sendEngagementData(forget?: boolean): Promise<void>;
+export declare function requestToSendEngagements(_payload: Dict, forget?: boolean): Promise<ServerResult>;

package/dist/esm/engagement/send.js

@@ -0,0 +1,96 @@
+/*! @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 } from '../core/state.js';
+import { Console, logFailure, warnAlways } from '../core/logger.js';
+import { cloneObject, isEmptyObj } from '../core/utils.js';
+import { engagement_transactions } from '../core/storage.js';
+import { is_apptics_disabled } from '../core/env.js';
+import { shouldTrackOrSendData } from '../core/consent.js';
+import { defer, clearDefer, withSendLock, freshItems, awaitUnlessClosing, sendBatch } from '../core/batch.js';
+import { isPermanentRefusal } from '../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 (is_apptics_disabled() || !shouldTrackOrSendData() || !_ZAP._engagementTracking) {
+        return Promise.resolve();
+    }
+    if (navigator.onLine == false) {
+        Console.warn('sendEngagementData: No Network'); // no i18n
+        return Promise.resolve();
+    }
+    // if we're busy sending, retry in .5s
+    if (_ZAP._sending) {
+        defer(sendEngagementData);
+        return Promise.resolve();
+    }
+    _ZAP._sending = true;
+    clearDefer();
+    return withSendLock('engagements', function () {
+        return freshItems(engagement_transactions, function (item) { return item.endtime != 0; }, function (item) { return item.starttime; }).then(function (engagement_items) {
+            if (engagement_items.length == 0) {
+                return;
+            }
+            let sessionObj = [], screenObj = [], eventObj = [], apiObj = [];
+            var _payload = {};
+            var sent = [];
+            cloneObject(engagement_items).forEach(function (item) {
+                const itemWithId = { ...item };
+                if (item.type == AP_CONSTANTS.EVENT) {
+                    eventObj.push(item);
+                }
+                else if (item.type == AP_CONSTANTS.SCREEN) {
+                    screenObj.push(item);
+                }
+                else if (item.type == AP_CONSTANTS.SESSION) {
+                    sessionObj.push(item);
+                }
+                else if (item.type == AP_CONSTANTS.API) {
+                    apiObj.push(item);
+                }
+                else {
+                    return;
+                }
+                sent.push(itemWithId);
+                delete item.id;
+                delete item.type;
+            });
+            if (eventObj.length > 0)
+                _payload.events = eventObj;
+            if (screenObj.length > 0)
+                _payload.screens = screenObj;
+            if (sessionObj.length > 0)
+                _payload.sessions = sessionObj;
+            if (apiObj.length > 0)
+                _payload.apis = apiObj;
+            if (isEmptyObj(_payload)) {
+                return;
+            }
+            return awaitUnlessClosing(requestToSendEngagements(_payload, forget).then(function () {
+                return engagement_transactions.remove(sent);
+            }, function (err) {
+                // the server will never accept this batch. Keeping it would block every later
+                // batch behind it for good, so it is dropped and said out loud
+                if (isPermanentRefusal(err)) {
+                    warnAlways('apptics: the server refused these engagement items, so they were dropped: ' + String(err && err.message)); // no i18n
+                    return engagement_transactions.remove(sent);
+                }
+                return Promise.reject(err);
+            }), forget, 'sendEngagementData'); // no i18n
+        });
+    }).catch(function (err) {
+        logFailure(AP_LOG_MODULE.API, 'sendEngagementData: ' + err); // no i18n
+    }).then(function () {
+        // something went wrong or we finished: allow this method to be recalled
+        _ZAP._sending = false;
+    });
+}
+// Function to send engagement data to server
+function requestToSendEngagements(_payload, forget) {
+    var label = 'requestToSendEngagements'; // no i18n
+    return sendBatch('engagement', label, _payload, forget); // no i18n
+}
+
+export { requestToSendEngagements, sendEngagementData };

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

@@ -0,0 +1,42 @@
+import type { Dict, QueueItem } from '../types.js';
+export declare function currentScreen(): Promise<QueueItem | undefined>;
+/**
+ * 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.
+ */
+export declare function closeScreen(id: string, time: number): Promise<void>;
+/**
+ * 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.
+ */
+export declare function updateScreenWithEndtime(): Promise<void>;
+/**
+ * Track the session.
+ * @param sessionData A set of properties belonging to the session.
+ */
+export declare function trackSession(sessionData: Dict): Promise<void>;
+/** This tab's session when it has one, otherwise the newest open session in storage. */
+export declare function currentSession(): Promise<QueueItem | undefined>;
+/**
+ * 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.
+ */
+export declare function commitPendingSession(): Promise<void>;
+/** Forgets a session that never earned its place, on a tab closing inside the minimum. */
+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>;
+/**
+ * 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.
+ */
+export declare function endCurrentSession(): Promise<void>;
+/**
+ * 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.
+ */
+export declare function closeAbandonedSessions(): Promise<void>;
+export declare function checkAndUpdateSession(): Promise<void>;
+export declare function updateLastActiveTimeOfSession(): Promise<void>;