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

package/dist/esm/heatmap/send.js

@@ -0,0 +1,79 @@
+/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta | (c) Zoho Corporation Private Limited | see LICENSE */
+import { _ZAP } from '../core/state.js';
+import { Console, warnAlways } from '../core/logger.js';
+import { cloneObject } from '../core/utils.js';
+import { heatmap_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';
+import { hooks } from '../core/hooks.js';
+
+/**
+ * Sends queued heatmap records to heatmap/add.
+ *
+ * Shaped like the error and engagement senders, because the queue behaves the same way: records
+ * are stored first and sent on the flush timer, a failed send leaves them for the next one, and
+ * `forget` is used on page hide so the last batch survives the page going away.
+ *
+ * Gated on the server's own heatmap flag (getsdkconfig module 18), not on engagement: an app may
+ * want events while declining to have every click's coordinates recorded.
+ */
+function sendHeatmapData(forget) {
+    if (is_apptics_disabled() || !shouldTrackOrSendData() || !_ZAP._heatmapTracking) {
+        return Promise.resolve();
+    }
+    if (navigator.onLine == false) {
+        Console.warn('sendHeatmapData: No Network'); // no i18n
+        return Promise.resolve();
+    }
+    if (_ZAP._sending) {
+        defer(sendHeatmapData);
+        return Promise.resolve();
+    }
+    _ZAP._sending = true;
+    clearDefer();
+    return withSendLock('heatmaps', function () {
+        return freshItems(heatmap_transactions, function () { return true; }, 
+        // aged by when the record happened, not when its session began: a tab left open for
+        // days would otherwise make every new record look older than the retention window
+        // and have it dropped unsent
+        function (item) { return (item.triggered_time || item.session_start_time); }).then(function (items) {
+            if (items.length == 0) {
+                return;
+            }
+            var data = [];
+            var sent = [];
+            cloneObject(items).forEach(function (item) {
+                sent.push({ ...item });
+                // `id` is the queue's own key, not something the endpoint declares
+                delete item.id;
+                data.push(item);
+            });
+            return awaitUnlessClosing(requestToSendHeatmaps({ data: data }, forget).then(function () {
+                return heatmap_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 heatmap records, so they were dropped: ' + String(err && err.message)); // no i18n
+                    return heatmap_transactions.remove(sent);
+                }
+                return Promise.reject(err);
+            }), forget, 'sendHeatmapData'); // no i18n
+        });
+    }).catch(function (err) {
+        Console.log('sendHeatmapData:' + err); // no i18n
+    }).then(function () {
+        _ZAP._sending = false;
+    });
+}
+function requestToSendHeatmaps(_payload, forget) {
+    var label = 'requestToSendHeatmaps'; // no i18n
+    return sendBatch('heatmap', label, _payload, forget); // no i18n
+}
+// the scheduler flushes through this, so importing the heatmap entry is what puts heatmap
+// records on the flush timer at all
+hooks.sendHeatmaps = sendHeatmapData;
+
+export { requestToSendHeatmaps, sendHeatmapData };

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

@@ -0,0 +1,4 @@
+/** Turns capture on or off. Listeners are passive, so they never delay a click or a scroll. */
+export declare function enableHeatmap(status?: boolean): void;
+/** Forgets what this visit recorded. reset() calls it; the cap starts again from zero. */
+export declare function resetHeatmapSession(): void;

package/dist/esm/heatmap/track.js

@@ -0,0 +1,374 @@
+/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta | (c) Zoho Corporation Private Limited | see LICENSE */
+import { AP_LOG_MODULE, AP_CONFIG, AP_TRACKING_STATUS } from '../core/constants.js';
+import { getConfig, _ZAP } from '../core/state.js';
+import { Console, logFailure } from '../core/logger.js';
+import { nowMs, isEmpty, getNewUUID } from '../core/utils.js';
+import { heatmap_transactions } from '../core/storage.js';
+import { commitPendingSession } from '../engagement/session.js';
+import { getConnectionType, getNetworkStatus, getOrientation } from '../core/env.js';
+import { canTrackHeatmap, getTrackingStatus } from '../core/consent.js';
+import { screenForRecord } from '../engagement/track.js';
+import { hooks } from '../core/hooks.js';
+import { noteDebugActivity } from '../core/debug.js';
+
+/**
+ * Where people click and how far they scroll.
+ *
+ * Two shapes of record, and they behave very differently. A click is one discrete thing and is
+ * recorded as it happens. Scrolling fires continuously — hundreds of events for one flick of a
+ * wheel — so it is coalesced into one record per gesture: a burst of scrolling that ends when the
+ * page has been still for a moment. Recording every scroll event would swamp the queue, the
+ * batch and the user's bandwidth, and would say nothing a single record per gesture does not.
+ */
+/** How long the page must be still before a scroll burst counts as one finished gesture. */
+const SCROLL_IDLE_MS = 150;
+/** Clicks closer than this in time and space count as one angry repetition. */
+const RAGE_WINDOW_MS = 1000;
+const RAGE_RADIUS_PX = 30;
+const RAGE_COUNT = 3;
+/** How long a click has to change something before it is called dead. */
+const DEAD_CLICK_MS = 1500;
+/** Longest element label we keep; enough to identify a control, short enough not to be content. */
+const LABEL_MAX = 80;
+/** heatMapObjectSDK caps screen, url_path and element_label at 500 characters. */
+const FIELD_MAX = 500;
+var installed = false;
+var recorded = 0;
+/** Recent clicks, for spotting a rage burst. */
+var recentClicks = [];
+var scrollStart = 0;
+var scrollStartX = 0;
+var scrollStartY = 0;
+var scrollTimer = null;
+/**
+ * Where the page was before the current gesture began.
+ *
+ * A scroll event fires *after* the position has already changed, so the first event of a burst
+ * reports somewhere the page has moved to, not where it started. Measuring from that loses the
+ * first increment of every gesture, and loses a single-event jump — an anchor link or a "back to
+ * top" button — completely, which is exactly the movement worth seeing on a scroll map.
+ */
+var lastX = 0;
+var lastY = 0;
+/** Whether a record may still be stored, or the visit has produced enough. */
+function underCap() {
+    var cap = getConfig('heatmap_max_per_session');
+    if (typeof cap !== 'number' || cap <= 0) {
+        cap = AP_CONFIG.heatmap_max_per_session;
+    }
+    if (recorded >= cap) {
+        if (recorded === cap) {
+            recorded++; // said once, not on every event for the rest of the visit
+            Console.log('apptics.heatmap: reached ' + cap + ' records for this session, pausing capture'); // no i18n
+        }
+        return false;
+    }
+    return true;
+}
+/** The page's full scrollable height, which is what a scroll depth is a fraction of. */
+function contentHeight() {
+    var doc = document.documentElement;
+    var body = document.body;
+    return Math.max(doc ? doc.scrollHeight : 0, body ? body.scrollHeight : 0, doc ? doc.clientHeight : 0);
+}
+/**
+ * A 0-1 fraction, to three decimals.
+ *
+ * Clamped because the inputs can exceed each other: a page that has not laid out yet reports a
+ * content height of 0, and a rubber-band scroll puts the viewport bottom past the document end.
+ * Both produce a "fraction" far outside 0-1, which is meaningless on a heatmap.
+ */
+function fraction(part, whole) {
+    if (!whole || whole <= 0) {
+        return 0;
+    }
+    var value = part / whole;
+    if (value < 0) {
+        value = 0;
+    }
+    if (value > 1) {
+        value = 1;
+    }
+    return Math.round(value * 1000) / 1000;
+}
+function viewportWidth() {
+    return window.innerWidth || (document.documentElement ? document.documentElement.clientWidth : 0) || 1;
+}
+/** Whether the element, or something it sits inside, is meant to be clicked. */
+function clickableAncestor(node) {
+    var depth = 0;
+    while (node && depth < 10) {
+        var tag = node.tagName ? node.tagName.toLowerCase() : ''; // no i18n
+        var role = node.getAttribute ? node.getAttribute('role') : null; // no i18n
+        if (tag === 'a' || tag === 'button' || tag === 'input' || tag === 'select' || tag === 'textarea' // no i18n
+            || tag === 'summary' || tag === 'label' // no i18n
+            || role === 'button' || role === 'link' || role === 'tab' || role === 'menuitem' // no i18n
+            || (node.hasAttribute && node.hasAttribute('onclick'))) { // no i18n
+            return node;
+        }
+        node = node.parentElement;
+        depth++;
+    }
+    return null;
+}
+/**
+ * A name for the element that was clicked.
+ *
+ * Attributes an author chose come first, because they are deliberate and stable. Visible text is
+ * the last resort and is skipped entirely when the user has opted out of PII: the text of a
+ * control can be a person's name, an email address or the contents of their cart.
+ */
+function labelFor(node) {
+    if (!node) {
+        return ''; // no i18n
+    }
+    var attributes = ['data-ap-label', 'apeventaction', 'aria-label', 'name', 'id', 'title']; // no i18n
+    for (var i = 0; i < attributes.length; i++) {
+        var value = node.getAttribute ? node.getAttribute(attributes[i]) : null;
+        if (!isEmpty(value)) {
+            return String(value).slice(0, LABEL_MAX);
+        }
+    }
+    var tag = node.tagName ? node.tagName.toLowerCase() : 'element'; // no i18n
+    if (getTrackingStatus() !== AP_TRACKING_STATUS.USAGE_TRACKING_WITH_PII) {
+        // without consent for PII the shape of the control is all we say
+        var role = node.getAttribute ? node.getAttribute('role') : null; // no i18n
+        return isEmpty(role) ? tag : tag + '[' + role + ']'; // no i18n
+    }
+    var text = (node.textContent || '').replace(/\s+/g, ' ').trim(); // no i18n
+    return isEmpty(text) ? tag : text.slice(0, LABEL_MAX);
+}
+/**
+ * A stable number for the element, so the console can group every click on one control together.
+ * Derived from its position in the tree rather than from its text, so it survives a label change
+ * and carries nothing a person typed.
+ */
+function triggeredId(node) {
+    if (!node) {
+        return 0;
+    }
+    var path = ''; // no i18n
+    var current = node;
+    var depth = 0;
+    while (current && depth < 12) {
+        var parent = current.parentElement;
+        var index = 0;
+        if (parent) {
+            var children = parent.children;
+            for (var i = 0; i < children.length; i++) {
+                if (children[i] === current) {
+                    index = i;
+                    break;
+                }
+            }
+        }
+        path = '/' + (current.tagName || '?') + ':' + index + path; // no i18n
+        current = parent;
+        depth++;
+    }
+    // FNV-1a, kept positive: a short stable number, not a cryptographic digest
+    var hash = 2166136261;
+    for (var c = 0; c < path.length; c++) {
+        hash ^= path.charCodeAt(c);
+        hash = (hash * 16777619) >>> 0;
+    }
+    return hash;
+}
+/** Whether this click is part of a burst of repeated clicks in the same spot. */
+function isRageClick(x, y, at) {
+    recentClicks = recentClicks.filter(function (click) { return at - click.at <= RAGE_WINDOW_MS; });
+    recentClicks.push({ at: at, x: x, y: y });
+    var near = recentClicks.filter(function (click) {
+        return Math.abs(click.x - x) <= RAGE_RADIUS_PX && Math.abs(click.y - y) <= RAGE_RADIUS_PX;
+    });
+    return near.length >= RAGE_COUNT;
+}
+/** The fields every record carries, whatever kind it is. */
+function common() {
+    return {
+        id: getNewUUID(),
+        session_start_time: _ZAP._current_session.starttime || nowMs(),
+        // without this the server has no way to order records within a session: session_start_time
+        // is the same for every one of them
+        triggered_time: nowMs(),
+        // the screen inScreen() or automatic screen tracking last named, or else the page, named
+        // as automatic tracking would name it and recorded as a screen view so engagement/add has it
+        screen: String(screenForRecord()).slice(0, FIELD_MAX),
+        url_path: String(window.location.pathname).slice(0, FIELD_MAX),
+        screen_width: window.screen ? window.screen.width : 0,
+        screen_height: window.screen ? window.screen.height : 0,
+        content_height: contentHeight(),
+        orientation: getOrientation(),
+        network_status: getNetworkStatus(),
+        edge_type: _ZAP._device_info.connectionType || getConnectionType(),
+        scroll_offset_x: Math.round(window.scrollX || window.pageXOffset || 0),
+        scroll_offset_y: Math.round(window.scrollY || window.pageYOffset || 0),
+    };
+}
+function store(record) {
+    recorded++;
+    noteDebugActivity();
+    // a heatmap record is worth a session in the same way an event is
+    commitPendingSession();
+    heatmap_transactions.add(record);
+    Console.dir(record);
+}
+function onPointerDown(event) {
+    if (!canTrackHeatmap('heatmap') || !underCap()) { // no i18n
+        return;
+    }
+    try {
+        var at = nowMs();
+        var target = event.target;
+        var clickable = clickableAncestor(target);
+        var named = clickable || target;
+        var x = Math.round(event.clientX);
+        var y = Math.round(event.clientY);
+        var height = contentHeight() || 1;
+        var pointerType = event.pointerType;
+        var record = Object.assign(common(), {
+            // TODO: send 'buttonclick' for a clickable target once the server accepts it. Held at
+            // 'default' for now while heatmap/add is still refusing payloads; `is_clickable`
+            // already carries the same information, so nothing is lost meanwhile.
+            triggered_type: 'default', // no i18n
+            gesture_type: 'click', // no i18n
+            gesture_duration: 0,
+            input_type: isEmpty(pointerType) ? 'mouse' : String(pointerType), // no i18n
+            element_label: labelFor(named),
+            triggered_id: triggeredId(named),
+            coordinate_x: x,
+            coordinate_y: y,
+            normalized_x: fraction(x, viewportWidth()),
+            normalized_y: fraction((window.scrollY || 0) + y, height),
+            velocity: 0,
+            is_clickable: clickable ? 1 : 0,
+            is_rage_click: isRageClick(x, y, at) ? 1 : 0,
+            is_dead_click: 0,
+        });
+        store(record);
+        watchForDeadClick(record, target);
+    }
+    catch (err) {
+        logFailure(AP_LOG_MODULE.HEATMAP, 'apptics.heatmap: click capture failed: ' + String(err)); // no i18n
+    }
+}
+/**
+ * A click on something that was not clickable and changed nothing is a click someone expected to
+ * work. Decided after the fact: the record is already stored, and is updated in place if nothing
+ * happened, so the click is never lost waiting to find out.
+ */
+function watchForDeadClick(record, target) {
+    if (record.is_clickable === 1 || typeof MutationObserver !== 'function') { // no i18n
+        return;
+    }
+    var changed = false;
+    var url = window.location.href;
+    var observer = new MutationObserver(function () { changed = true; });
+    try {
+        observer.observe(document.documentElement, { childList: true, subtree: true, attributes: true });
+    }
+    catch (err) {
+        return;
+    }
+    setTimeout(function () {
+        observer.disconnect();
+        if (!changed && window.location.href === url) {
+            record.is_dead_click = 1;
+            heatmap_transactions.update(record);
+        }
+    }, DEAD_CLICK_MS);
+}
+function onScroll() {
+    if (!canTrackHeatmap('heatmap') || !underCap()) { // no i18n
+        return;
+    }
+    if (scrollTimer === null) {
+        scrollStart = nowMs();
+        scrollStartX = lastX;
+        scrollStartY = lastY;
+    }
+    else {
+        clearTimeout(scrollTimer);
+    }
+    scrollTimer = setTimeout(endScrollGesture, SCROLL_IDLE_MS);
+}
+/** One record for the whole burst, once the page has been still for SCROLL_IDLE_MS. */
+function endScrollGesture() {
+    scrollTimer = null;
+    try {
+        var endX = Math.round(window.scrollX || 0);
+        var endY = Math.round(window.scrollY || 0);
+        var dx = endX - scrollStartX;
+        var dy = endY - scrollStartY;
+        lastX = endX;
+        lastY = endY;
+        if (dx === 0 && dy === 0) {
+            return;
+        }
+        var duration = Math.max(1, nowMs() - scrollStart);
+        var distance = Math.sqrt(dx * dx + dy * dy);
+        var direction = Math.abs(dy) >= Math.abs(dx)
+            ? (dy > 0 ? 'down-scroll' : 'up-scroll') // no i18n
+            : (dx > 0 ? 'right-scroll' : 'left-scroll'); // no i18n
+        var height = contentHeight() || 1;
+        store(Object.assign(common(), {
+            // the server accepts only event|default|buttonclick here; what kind of movement it
+            // was belongs in gesture_type. input_type is left off rather than invented: a wheel
+            // carries no pointer type, and the intended vocabulary has no value for "unknown"
+            triggered_type: 'default', // no i18n
+            gesture_type: direction,
+            gesture_duration: Math.round(duration),
+            element_label: '', // no i18n
+            triggered_id: 0,
+            coordinate_x: endX,
+            coordinate_y: endY,
+            normalized_x: 0,
+            // how far down the page the gesture left them, which is what a scroll map reads
+            normalized_y: fraction(endY + (window.innerHeight || 0), height),
+            velocity: Math.round((distance / duration) * 1000),
+            is_clickable: 0,
+            is_rage_click: 0,
+            is_dead_click: 0,
+        }));
+    }
+    catch (err) {
+        logFailure(AP_LOG_MODULE.HEATMAP, 'apptics.heatmap: scroll capture failed: ' + String(err)); // no i18n
+    }
+}
+/** Turns capture on or off. Listeners are passive, so they never delay a click or a scroll. */
+function enableHeatmap(status) {
+    var wanted = typeof status === 'boolean' ? status : true; // no i18n
+    if (wanted === installed) {
+        return;
+    }
+    if (wanted) {
+        // where the page already is, so the first gesture is measured from here and not from 0
+        lastX = Math.round(window.scrollX || 0);
+        lastY = Math.round(window.scrollY || 0);
+        window.addEventListener('pointerdown', onPointerDown, { capture: true, passive: true }); // no i18n
+        window.addEventListener('scroll', onScroll, { capture: true, passive: true }); // no i18n
+        installed = true;
+        Console.log('apptics.heatmap: capturing clicks and scrolls'); // no i18n
+        return;
+    }
+    window.removeEventListener('pointerdown', onPointerDown, true); // no i18n
+    window.removeEventListener('scroll', onScroll, true); // no i18n
+    if (scrollTimer !== null) {
+        clearTimeout(scrollTimer);
+        scrollTimer = null;
+    }
+    installed = false;
+    Console.log('apptics.heatmap: capture stopped'); // no i18n
+}
+/** Forgets what this visit recorded. reset() calls it; the cap starts again from zero. */
+function resetHeatmapSession() {
+    recorded = 0;
+    recentClicks = [];
+    lastX = 0;
+    lastY = 0;
+}
+// init() and reset() drive capture through these, so neither has to import this module
+hooks.enableHeatmap = enableHeatmap;
+hooks.resetHeatmap = resetHeatmapSession;
+
+export { enableHeatmap, resetHeatmapSession };

package/dist/esm/index.d.ts

@@ -0,0 +1,68 @@
+import { AP_FEEDBACK_TYPE, AP_TRACKING_STATUS } from './core/constants.js';
+import { init as initImpl, ready as readyImpl, reset as resetImpl } from './lifecycle.js';
+import { enableApiTracking as enableApiTrackingImpl } from './engagement/auto-api.js';
+import { DefinedEvents } from './engagement/defined-events.js';
+import { ApiTrackingBuilder } from './engagement/api-rules.js';
+import { enableGlobalErrorHandler as enableGlobalErrorHandlerImpl } from './errors/track.js';
+import { getUser as getUserImpl, UserBuilder, users } from './user/index.js';
+import { getTrackingStatus as getTrackingStatusImpl, setTrackingStatus as setTrackingStatusImpl } from './core/consent.js';
+import { flush as flushImpl } from './scheduler.js';
+import { addDiagnosticsInfo as addDiagnosticsInfoImpl, addFeedbackLog as addFeedbackLogImpl } from './feedback/logs.js';
+import type { AppticsApi } from './types.js';
+import { disableDebug as disableDebugImpl, enableDebug as enableDebugImpl } from './core/debug.js';
+import { AppticsLogger } from './remotelog/logger.js';
+export type { AppticsLogger as AppticsLoggerApi } from './remotelog/logger.js';
+export type { AppticsApi, AppticsConfig, ErrorLike, FeedbackType, Properties, TrackingStatus, UserInfo, UserValidationResult, } from './types.js';
+/** Android's Apptics: `Apptics.init(config)` starts the SDK. */
+export declare const Apptics: {
+    /** Starts the SDK. The config object is required; the console snippet supplies it via auto-init. */
+    init: typeof initImpl;
+};
+export declare const ready: typeof readyImpl;
+/** Android's AppticsEvents: `addEvent(name, group?, properties?)`, or `addEvent(DefinedEvents.X, properties?)`. */
+export declare const AppticsEvents: {
+    addEvent: AppticsApi["AppticsEvents"]["addEvent"];
+};
+/** Apptics' defined events, as Android's DefinedEvents, to log with AppticsEvents.addEvent. */
+export { DefinedEvents };
+export type { DefinedEvent } from './engagement/defined-events.js';
+/** Android's AppticsScreenTracker: inScreen(name) returns the view's id, outScreen(id) ends it. */
+export declare const AppticsScreenTracker: AppticsApi['AppticsScreenTracker'];
+/** Android's AppticsApiTracker: startTrackApi / endTrackApi, and configure for the rules. */
+export declare const AppticsApiTracker: AppticsApi['AppticsApiTracker'];
+export { ApiTrackingBuilder };
+export type { ApiTrackingConfig } from './engagement/api-rules.js';
+/** Turns automatic API tracking on or off; the `track_api` config flag is the usual way to set it. */
+export declare const enableApiTracking: typeof enableApiTrackingImpl;
+/** Reports an error the app caught, or an `error` / `unhandledrejection` event. */
+export declare const AppticsTrackError: AppticsApi["AppticsTrackError"];
+export declare const enableGlobalErrorHandler: typeof enableGlobalErrorHandlerImpl;
+/** Registers the signed-in user; properties may be a plain object or UserBuilder.build(). */
+export declare const AppticsSetUser: AppticsApi["AppticsSetUser"];
+export declare const getUser: typeof getUserImpl;
+export declare const setTrackingStatus: typeof setTrackingStatusImpl;
+export declare const getTrackingStatus: typeof getTrackingStatusImpl;
+export declare const flush: typeof flushImpl;
+/** Records a line for the next feedback submission. Costs nothing until feedback is sent. */
+export declare const addFeedbackLog: typeof addFeedbackLogImpl;
+/** Records a diagnostics key/value, grouped under `heading`, for the next feedback submission. */
+export declare const addDiagnosticsInfo: typeof addDiagnosticsInfoImpl;
+/**
+ * Turns debug mode on; works before init(), and wins over `debug` in init().
+ *
+ * On, engagement, exception and log go to their `debug/` twins and the answers carry a request id
+ * and a link into the server's own logs. It switches itself off after an hour with nothing
+ * tracked, so a forgotten tab stops tracing on its own.
+ */
+export declare const enableDebug: typeof enableDebugImpl;
+/** Turns debug mode off; works before init(), and wins over `debug` in init(). */
+export declare const disableDebug: typeof disableDebugImpl;
+export declare const reset: typeof resetImpl;
+/**
+ * Android's AppticsLogger, shown on the console's Remote Logger page. Off until
+ * `AppticsLogger.enable()`; then `AppticsLogger.v / d / i / w / e(tag, message, ...details)`.
+ */
+export { AppticsLogger };
+export { AP_FEEDBACK_TYPE, AP_TRACKING_STATUS, UserBuilder, users };
+declare const apptics: AppticsApi;
+export default apptics;

package/dist/esm/index.js

@@ -0,0 +1,122 @@
+/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta | (c) Zoho Corporation Private Limited | see LICENSE */
+import { AP_FEEDBACK_TYPE, AP_TRACKING_STATUS } from './core/constants.js';
+import { guard } from './core/guard.js';
+import { init, reset as reset$1, ready as ready$1 } from './lifecycle.js';
+import { enableApiTracking as enableApiTracking$1 } from './engagement/auto-api.js';
+import { startTrackApi, trackEvent, endTrackApiAt, outScreenAt, inScreenAt } from './engagement/track.js';
+import { DefinedEvents } from './engagement/defined-events.js';
+import { nowMs, getNewUUID } from './core/utils.js';
+import { validateScreenName } from './core/validate.js';
+import { ApiTrackingBuilder, configureApiTracking } from './engagement/api-rules.js';
+import { trackError, enableGlobalErrorHandler as enableGlobalErrorHandler$1 } from './errors/track.js';
+import { users, setUser, getUser as getUser$1 } from './user/index.js';
+export { UserBuilder } from './user/index.js';
+import { getTrackingStatus as getTrackingStatus$1, setTrackingStatus as setTrackingStatus$1 } from './core/consent.js';
+import { flush as flush$1 } from './scheduler.js';
+import { addDiagnosticsInfo as addDiagnosticsInfo$1, addFeedbackLog as addFeedbackLog$1 } from './feedback/logs.js';
+import { scheduleAutoInit } from './auto-init.js';
+import { disableDebug as disableDebug$1, enableDebug as enableDebug$1 } from './core/debug.js';
+import { AppticsLogger } from './remotelog/logger.js';
+
+/** Android's Apptics: `Apptics.init(config)` starts the SDK. */
+const Apptics = {
+    /** Starts the SDK. The config object is required; the console snippet supplies it via auto-init. */
+    init: guard('Apptics.init', init), // no i18n
+};
+const ready = guard('ready', ready$1); // no i18n
+/** Android's AppticsEvents: `addEvent(name, group?, properties?)`, or `addEvent(DefinedEvents.X, properties?)`. */
+const AppticsEvents = {
+    addEvent: guard('AppticsEvents.addEvent', trackEvent), // no i18n
+};
+const inScreenGuarded = guard('AppticsScreenTracker.inScreen', inScreenAt); // no i18n
+const outScreenGuarded = guard('AppticsScreenTracker.outScreen', outScreenAt); // no i18n
+/** Android's AppticsScreenTracker: inScreen(name) returns the view's id, outScreen(id) ends it. */
+const AppticsScreenTracker = {
+    /**
+     * Records a screen view and returns its id. The view ends at the next screen, when the page is
+     * hidden or its session ends, or when the id is handed to outScreen. '' for an invalid name.
+     */
+    inScreen: function (screenName, properties) {
+        if (!validateScreenName(screenName)) {
+            // inScreenAt reports it; the caller still needs an answer now
+            inScreenGuarded(screenName, properties, '', nowMs()); // no i18n
+            return ''; // no i18n
+        }
+        // the id and the start now, so both are right even when start-up is still running
+        var id = getNewUUID();
+        inScreenGuarded(screenName, properties, id, nowMs());
+        return id;
+    },
+    /** Ends the screen view inScreen began, before the next screen would. */
+    outScreen: function (id) {
+        outScreenGuarded(id, nowMs());
+    },
+};
+const endTrackApiGuarded = guard('AppticsApiTracker.endTrackApi', endTrackApiAt); // no i18n
+/** Android's AppticsApiTracker: startTrackApi / endTrackApi, and configure for the rules. */
+const AppticsApiTracker = {
+    /** Begins timing one call: returns the id endTrackApi takes. */
+    startTrackApi: guard('AppticsApiTracker.startTrackApi', startTrackApi), // no i18n
+    /** Finishes a call startTrackApi began and records it. */
+    endTrackApi: function (id, responseCode, responseMessage) {
+        // the end time now, not when a call made during start-up is replayed
+        endTrackApiGuarded(id, responseCode, responseMessage, nowMs());
+    },
+    /** The rules API tracking records by, from ApiTrackingBuilder. Works before Apptics.init(). */
+    configure: guard('AppticsApiTracker.configure', configureApiTracking), // no i18n
+};
+/** Turns automatic API tracking on or off; the `track_api` config flag is the usual way to set it. */
+const enableApiTracking = guard('enableApiTracking', enableApiTracking$1); // no i18n
+/** Reports an error the app caught, or an `error` / `unhandledrejection` event. */
+const AppticsTrackError = guard('AppticsTrackError', trackError); // no i18n
+const enableGlobalErrorHandler = guard('enableGlobalErrorHandler', enableGlobalErrorHandler$1); // no i18n
+/** Registers the signed-in user; properties may be a plain object or UserBuilder.build(). */
+const AppticsSetUser = guard('AppticsSetUser', setUser); // no i18n
+const getUser = guard('getUser', getUser$1); // no i18n
+const setTrackingStatus = guard('setTrackingStatus', setTrackingStatus$1); // no i18n
+const getTrackingStatus = guard('getTrackingStatus', getTrackingStatus$1); // no i18n
+const flush = guard('flush', flush$1); // no i18n
+/** Records a line for the next feedback submission. Costs nothing until feedback is sent. */
+const addFeedbackLog = guard('addFeedbackLog', addFeedbackLog$1); // no i18n
+/** Records a diagnostics key/value, grouped under `heading`, for the next feedback submission. */
+const addDiagnosticsInfo = guard('addDiagnosticsInfo', addDiagnosticsInfo$1); // no i18n
+/**
+ * Turns debug mode on; works before init(), and wins over `debug` in init().
+ *
+ * On, engagement, exception and log go to their `debug/` twins and the answers carry a request id
+ * and a link into the server's own logs. It switches itself off after an hour with nothing
+ * tracked, so a forgotten tab stops tracing on its own.
+ */
+const enableDebug = guard('enableDebug', enableDebug$1); // no i18n
+/** Turns debug mode off; works before init(), and wins over `debug` in init(). */
+const disableDebug = guard('disableDebug', disableDebug$1); // no i18n
+const reset = guard('reset', reset$1); // no i18n
+const apptics = {
+    Apptics,
+    AppticsEvents,
+    AppticsScreenTracker,
+    AppticsApiTracker,
+    AppticsLogger,
+    DefinedEvents,
+    ApiTrackingBuilder,
+    ready,
+    enableDebug,
+    disableDebug,
+    enableApiTracking,
+    AppticsTrackError,
+    enableGlobalErrorHandler,
+    AppticsSetUser,
+    getUser,
+    users,
+    setTrackingStatus,
+    getTrackingStatus,
+    flush,
+    addFeedbackLog,
+    addDiagnosticsInfo,
+    reset,
+    AP_TRACKING_STATUS,
+    AP_FEEDBACK_TYPE,
+};
+scheduleAutoInit(Apptics);
+
+export { AP_FEEDBACK_TYPE, AP_TRACKING_STATUS, ApiTrackingBuilder, Apptics, AppticsApiTracker, AppticsEvents, AppticsLogger, AppticsScreenTracker, AppticsSetUser, AppticsTrackError, DefinedEvents, addDiagnosticsInfo, addFeedbackLog, apptics as default, disableDebug, enableApiTracking, enableDebug, enableGlobalErrorHandler, flush, getTrackingStatus, getUser, ready, reset, setTrackingStatus, users };

package/dist/esm/lifecycle.d.ts

@@ -0,0 +1,14 @@
+import type { AppticsConfig } from './types.js';
+/**
+ * Starts the SDK. The config object is required: pass it directly, or let the console snippet
+ * supply it (auto-init reads window.appticssettings._defaultoptions and calls init with it).
+ * Returns true when the config has serviceUrl, zak, identifier and appversion and start-up has
+ * begun (see ready()), false when it was already running, the config is missing or incomplete, or
+ * there is no browser. Start-up calls app/addversion with those four, which answers with aaid, the
+ * portal and project ids and the rest; then device/add registers the browser, as in 1.x.
+ */
+export declare function init(config: AppticsConfig): boolean;
+/** Resolves true once start-up has finished, false if init() refused or storage is unusable. */
+export declare function ready(): Promise<boolean>;
+/** Clears stored identity and queues, then starts again from the snippet. */
+export declare function reset(): void;