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

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

@@ -0,0 +1,301 @@
+/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta.1 | (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`.
+ */
+/** A path as screen_routes compares it: no query or fragment, no trailing slash but on the root. */
+function routePath(path) {
+    var bare = String(path || '').split(/[?#]/)[0] || '/'; // no i18n
+    return bare.length > 1 ? bare.replace(/\/+$/, '') : bare; // no i18n
+}
+/** 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
+}
+/** Whether a pattern segment is a wildcard: `{id}`, `:id` or `*`. */
+function isWildcard(segment) {
+    return segment === '*' || /^\{[^/]*\}$/.test(segment) || /^:[^/]+$/.test(segment); // no i18n
+}
+/** Whether a route pattern matches a path: every segment, `{id}`, `:id` and `*` matching any one. */
+function patternMatches(pattern, path) {
+    var segments = routePath(pattern).split('/'); // no i18n
+    var actual = path.split('/'); // no i18n
+    if (segments.length !== actual.length) {
+        return false;
+    }
+    for (var j = 0; j < segments.length; j++) {
+        var seg = segments[j];
+        if (!isWildcard(seg) && seg !== actual[j]) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * The name screen_routes gives a path, or the path itself when no entry matches. Tried in order:
+ * a route pattern records the path with its variable segments as `*` (`/users/{id}/orders`
+ * claims `/users/1/orders`, not `/users/1/orders/2`); an exact path or a regular expression
+ * records the name the entry gives. Matched on the path without its query.
+ */
+function applyRoutes(path) {
+    var routes = _ZAP._config.screen_routes;
+    if (!routes || routes.length === 0) {
+        return path;
+    }
+    var bare = routePath(path);
+    for (var i = 0; i < routes.length; i++) {
+        var route = routes[i];
+        if (route.kind === 'equals' && route.path === bare) { // no i18n
+            return route.name;
+        }
+        if (route.kind === 'regex') { // no i18n
+            route.regex.lastIndex = 0; // a /g regular expression keeps a position between tests
+            if (route.regex.test(bare)) {
+                return route.name;
+            }
+        }
+        if (route.kind === 'pattern' && patternMatches(route.pattern, bare)) { // no i18n
+            return routePath(route.pattern).split('/').map((s) => (isWildcard(s) ? '*' : s)).join('/'); // no i18n
+        }
+    }
+    return path;
+}
+/**
+ * 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(applyRoutes(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.
+ *
+ * A history call that leaves the screen where it is, is not a navigation. Next.js and other
+ * routers replaceState the same url right after a route change, to store their state or the
+ * scroll position. Treated as one, it cancelled the view still waiting to settle, and the check
+ * that followed found the url already seen and recorded nothing: the page went untracked and the
+ * view before it was never ended.
+ */
+function navigated() {
+    var name = currentName();
+    if (name !== '' && (name === pendingName || (pendingName === '' && name === lastName))) { // no i18n
+        return;
+    }
+    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, routePath };

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.1 | (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,101 @@
+/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta.1 | (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;
+                // which tabs share a session, which tab shows a screen and when it was last seen: the
+                // SDK's own bookkeeping, not part of the payload
+                delete item.tabs;
+                delete item.tab;
+                delete item.lastseen;
+            });
+            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,51 @@
+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 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.
+ */
+export declare function currentSession(): Promise<QueueItem | undefined>;
+export declare function tabId(): string;
+/** Takes this tab's lock, held until the page is gone. Once per page. */
+export declare function holdTabLock(): void;
+/** Ends the open screen views of tabs that are gone. Resolves right away without Web Locks. */
+export declare function closeScreensOfGoneTabs(): Promise<void>;
+/**
+ * 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>;
+/**
+ * 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.
+ */
+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>;