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

package/dist/esm/device/index.js

@@ -1,12 +1,13 @@
-/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta | (c) Zoho Corporation Private Limited | see LICENSE */
+/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta.1 | (c) Zoho Corporation Private Limited | see LICENSE */
 import { SDK_MODULE } from '../core/constants.js';
 import { _ZAP } from '../core/state.js';
 import { Console } from '../core/logger.js';
-import { isEmpty, isSuccess, compareTwoObjects } from '../core/utils.js';
-import { user_defaults, getKeyFromDeviceInfo } from '../core/storage.js';
+import { isEmpty, getNewUUID, isSuccess, compareTwoObjects } from '../core/utils.js';
+import { user_defaults, getKeyFromDeviceInfo, setDeviceInfoKey, storedTrackingStatus, reloadSettings } from '../core/storage.js';
+import { withLock } from '../core/locks.js';
 import { getTimeZone, getConnectionType, getReferringURL, getDevice, getBrowserVersion, getBrowser, getOS } from '../core/env.js';
 import { hasDoNotTrackEnabled } from '../core/consent.js';
-import { getHeaderParams, rejectIfDisabled, rejectIfOffline, apiHeaders, postToApptics, rejectIfNoDeviceIds } from '../core/transport.js';
+import { rejectIfDisabled, rejectIfOffline, apiHeaders, getHeaderParams, postToApptics, hasDeviceId, rejectIfNoDeviceIds } from '../core/transport.js';
 import { hooks } from '../core/hooks.js';
 import { applyStoredAppVersion } from './appversion.js';
 
@@ -93,7 +94,11 @@ function checkAndUpdateDeviceInfo() {
         // appreleaseversionid from app/addversion
         modelid: getKeyFromDeviceInfo('modelid'), // no i18n
         appreleaseversionid: getKeyFromDeviceInfo('appreleaseversionid'), // no i18n
-        timezone: getTimeZone()
+        timezone: getTimeZone(),
+        // kept here rather than as keys of their own: the id the browser is registered under, and
+        // whether it has had a session (a session's firstsession says so)
+        uuid: _ZAP._uuid || getKeyFromDeviceInfo('uuid'), // no i18n
+        hadsession: getKeyFromDeviceInfo('hadsession') === true ? true : undefined, // no i18n
     };
     // the rebuild above starts from browser facts, so the ids app/addversion returned are put
     // back before anything is stored or compared
@@ -141,7 +146,7 @@ function addOrUpdateDeviceID(device_info, previous) {
  * out as an empty header.
  */
 const DEVICE_RESPONSE_KEYS = ['deviceid', 'anonymousid', 'aaid', 'apid', 'mapid', 'appversionid', 'osversionid', 'timezoneid', 'platformid', 'devicetypeid', 'modelid']; // no i18n
-/** Copies server-assigned ids into state and persists device info. */
+/** Copies server-assigned ids into state and persists device info; resolves once it is stored. */
 function applyDeviceResponse(data) {
     DEVICE_RESPONSE_KEYS.forEach(function (key) {
         // an id the answer does not mention is one we already hold, or one we never had:
@@ -157,12 +162,81 @@ function applyDeviceResponse(data) {
     if (!isEmpty(data.mapid)) {
         _ZAP._mapid = data.mapid;
     }
-    // Update the new device info into the localstorage
-    user_defaults.add('device_info', _ZAP._device_info); // no i18n
+    // stored before the registration counts as done, so another tab waiting to register reads it
+    return user_defaults.save('device_info', _ZAP._device_info); // no i18n
+}
+/**
+ * The browser's uuid: the one in storage, or a new one stored now. Every tab of the site uses the
+ * same one, because the device is registered under it.
+ */
+function useStoredUuid() {
+    // kept in device_info: it is the id this browser is registered under
+    var uuid = getKeyFromDeviceInfo('uuid'); // no i18n
+    if (isEmpty(uuid)) {
+        uuid = getNewUUID();
+        setDeviceInfoKey('uuid', uuid); // no i18n
+    }
+    _ZAP._uuid = uuid;
+}
+/**
+ * The ids another tab of this site registered after this one loaded its settings: those are in
+ * storage but not in this tab's copy. Resolves with them, applied to this tab, or null when the
+ * browser is still unregistered and this tab has to register it.
+ */
+function adoptRegisteredDevice() {
+    return reloadSettings(['device_info']).then(function () {
+        var stored = user_defaults.item('device_info') || {}; // no i18n
+        if (isEmpty(stored.deviceid) || isEmpty(stored.anonymousid)) {
+            return null;
+        }
+        // the device is registered under the uuid the other tab sent
+        if (!isEmpty(stored.uuid)) {
+            _ZAP._uuid = stored.uuid;
+        }
+        Console.log('registerDeviceWithApptics: another tab registered this browser, using its device ' + stored.deviceid); // no i18n
+        return applyDeviceResponse(stored).then(function () {
+            return { result: 'success', data: stored }; // no i18n
+        });
+    });
+}
+/**
+ * Sets up this browser's device at start-up: the uuid, the device info, and a registration when
+ * the browser has none.
+ *
+ * Settings are this tab's own copy, loaded when it started. On a browser with no device yet, two
+ * tabs started together would each register it and store two devices, so the first visit runs
+ * under a lock shared by every tab of the site: the tab that gets it re-reads storage, registers
+ * only when no other tab has, and keeps the lock until the new ids are stored. The next tab then
+ * finds them. Start-up goes on as soon as the device info is set, without waiting for the server.
+ */
+function prepareDevice() {
+    var cached = user_defaults.item('device_info') || {}; // no i18n
+    if (!isEmpty(cached.deviceid) && !isEmpty(cached.anonymousid)) {
+        useStoredUuid();
+        checkAndUpdateDeviceInfo();
+        return Promise.resolve();
+    }
+    return new Promise(function (resolve) {
+        withLock('device', function () {
+            return reloadSettings(['device_info']).then(function () {
+                useStoredUuid();
+                checkAndUpdateDeviceInfo();
+                resolve();
+                // held until a registration this started is stored, or has failed
+                return deviceReady();
+            });
+        }).catch(function (err) {
+            Console.log('prepareDevice: ' + err); // no i18n
+        }).then(function () {
+            resolve();
+        });
+    });
 }
 /** True while the device has no server ids, so nothing can be sent yet. */
 function needsDevice() {
-    return isEmpty(getHeaderParams('apid')) && isEmpty(getHeaderParams('mapid')); // no i18n
+    // the app ids from app/addversion, and the deviceid from device/add: either missing, and the
+    // device is registered before anything stored is sent
+    return (isEmpty(getHeaderParams('apid')) && isEmpty(getHeaderParams('mapid'))) || !hasDeviceId(); // no i18n
 }
 /**
  * Resolves once a registration that is in flight has settled, succeeded or not, and right away
@@ -195,8 +269,8 @@ function registerDeviceWithApptics() {
         return blocked;
     }
     if (!_ZAP._token) {
-        Console.warn(label + ': You must call apptics.init() first'); // no i18n
-        return Promise.reject(label + ': You must call apptics.init() first'); // no i18n
+        Console.warn(label + ': You must call Apptics.init() first'); // no i18n
+        return Promise.reject(label + ': You must call Apptics.init() first'); // no i18n
     }
     var offline = rejectIfOffline(label);
     if (offline) {
@@ -213,13 +287,21 @@ function registerDeviceWithApptics() {
             return;
         }
         _ZAP._regDeviceSending = true;
-        var payload = deviceBody(_ZAP._device_info);
-        // device/add is the one url that allows all four: zak and uuid identify the caller,
-        // apid and mapid the app. app/addversion has already answered with apid and mapid by
-        // the time registration runs, so the first call can carry them like every later one.
-        var headers = { zak: getHeaderParams('zak'), uuid: getHeaderParams('uuid'), ...apiHeaders() }; // no i18n
-        postToApptics('regdevice', payload, headers, label).then(function (result) {
-            applyDeviceResponse(result.data || {});
+        adoptRegisteredDevice().then(function (adopted) {
+            if (adopted) {
+                return adopted;
+            }
+            var payload = deviceBody(_ZAP._device_info);
+            // device/add is the one url that allows all four: zak and uuid identify the caller,
+            // apid and mapid the app. app/addversion has already answered with apid and mapid by
+            // the time registration runs, so the first call can carry them like every later one.
+            var headers = { zak: getHeaderParams('zak'), uuid: getHeaderParams('uuid'), ...apiHeaders() }; // no i18n
+            return postToApptics('regdevice', payload, headers, label).then(function (result) {
+                return applyDeviceResponse(result.data || {}).then(function () {
+                    return result;
+                });
+            });
+        }).then(function (result) {
             settleRegistration(true, result);
             resolve(result);
             // first visit: the ids exist now, so fetch the server settings right away
@@ -255,7 +337,9 @@ function getUpdatesFromServer() {
     return postToApptics('sdkconfig', '', apiHeaders(), label).then(function (result) {
         var data = result.data || {};
         applyServerFlags(data);
-        user_defaults.add('trackinfo', _ZAP._trackinfo); // no i18n
+        // the visitor's tracking status lives in trackinfo too, and is not the server's to replace
+        var saved = storedTrackingStatus();
+        user_defaults.add('trackinfo', saved === undefined ? _ZAP._trackinfo : Object.assign({}, _ZAP._trackinfo, { tracking_status: saved })); // no i18n
         Console.log('getUpdatesFromServer: ' + JSON.stringify(_ZAP._trackinfo)); // no i18n
         return data;
     });
@@ -314,10 +398,18 @@ function applyServerFlags(data) {
         _ZAP._remoteLoggerEnabled = data.remoteloggerenabled !== false;
         _ZAP._feedbackEnabled = data.feedbackenabled !== false;
     }
+    // screen recording, set up in the console: everything the form needs comes from here
     var quartz = (data.quartz && typeof data.quartz === 'object' ? data.quartz : {});
-    _ZAP._quartzEnabled = quartz.hasOwnProperty('quartz_enabled') // no i18n
-        ? quartz.quartz_enabled !== false
-        : data.quartzenabled !== false;
+    var text = function (value) {
+        return typeof value === 'string' ? value.trim() : ''; // no i18n
+    };
+    _ZAP._quartz = {
+        enabled: quartz.hasOwnProperty('quartz_enabled') ? quartz.quartz_enabled === true : data.quartzenabled === true, // no i18n
+        workspace: text(quartz.quartz_workspace),
+        department: text(quartz.quartz_department),
+        domain: text(quartz.quartz_domain),
+        cdnUrl: text(quartz.quartz_cdn_url),
+    };
     // when to ask again, which replaces polling on a fixed interval
     if (typeof data.next_check_after === 'number' && data.next_check_after > 0) {
         _ZAP._nextConfigCheck = data.next_check_after;
@@ -328,7 +420,14 @@ function applyServerFlags(data) {
         heatmaptracking: _ZAP._heatmapTracking,
         remoteloggerenabled: _ZAP._remoteLoggerEnabled,
         feedbackenabled: _ZAP._feedbackEnabled,
-        quartzenabled: _ZAP._quartzEnabled,
+        // in the server's own shape, so restoring it on the next visit reads it the same way
+        quartz: {
+            quartz_enabled: _ZAP._quartz.enabled,
+            quartz_workspace: _ZAP._quartz.workspace,
+            quartz_department: _ZAP._quartz.department,
+            quartz_domain: _ZAP._quartz.domain,
+            quartz_cdn_url: _ZAP._quartz.cdnUrl,
+        },
         shouldtrack: _ZAP._shouldTrack,
         next_check_after: _ZAP._nextConfigCheck
     };
@@ -359,4 +458,4 @@ function refreshServerSettings() {
 hooks.updateDevice = updateDeviceWithApptics;
 hooks.refreshDeviceInfo = checkAndUpdateDeviceInfo;
 
-export { addOrUpdateDeviceID, checkAndUpdateDeviceInfo, deviceReady, getUpdatesFromServer, needsDevice, refreshServerSettings, registerDeviceWithApptics, restoreServerSettings, updateDeviceWithApptics };
+export { addOrUpdateDeviceID, checkAndUpdateDeviceInfo, deviceReady, getUpdatesFromServer, needsDevice, prepareDevice, refreshServerSettings, registerDeviceWithApptics, restoreServerSettings, updateDeviceWithApptics };

package/dist/esm/engagement/api-rules.d.ts

@@ -1,62 +1,34 @@
-/**
- * What API tracking records, and under what name — Android's AppticsApiTracker.configure, built
- * with ApiTrackingBuilder the way user properties are built with UserBuilder:
- *
- *   configureApiTracking(new ApiTrackingBuilder()
- *       .allowOnlyDomains('api.zylker.com', 'api.zylker.in')
- *       .groupDomains('api.zylker.*')
- *       .ignoreEndpoint('/health', '/internal/**')
- *       .addPattern('/v2/catalog/{categoryId}/items/{itemId}')
- *       .build());
- *
- * Two jobs. Filtering decides whether a call is recorded at all: ignore rules first, and they
- * always win, then the allow lists. Normalization decides the path it is recorded under, so that
- * `/users/42/orders` and `/users/43/orders` are one endpoint on the console rather than two: the
- * query string goes, an explicit pattern is used when one matches, and otherwise numeric ids,
- * UUIDs and JWTs become `*`.
- *
- * Both apply to every call, the ones the fetch/XHR wrappers catch and the ones the app reports
- * with trackApi() or startTrackApi(), so one set of rules decides what the API page shows.
- */
 /** The rules, as ApiTrackingBuilder.build() returns them. Every list may be empty. */
 export interface ApiTrackingConfig {
-    ignoreDomains: string[];
-    allowOnlyDomains: string[];
-    allowOnlyTLDs: string[];
-    ignoreTLDs: string[];
-    ignoreDomainPrefixes: string[];
-    ignoreDomainSuffixes: string[];
-    groupDomains: string[];
-    ignoreEndpoints: string[];
-    patterns: string[];
-    preserveSegments: string[];
-    autoDetection: boolean;
+    /** URLs recorded, exactly; with any allow rule, only calls matching one are recorded. */
+    allowEquals: string[];
+    /** URLs never recorded, exactly. */
+    ignoreEquals: string[];
+    /** Regular expressions a recorded URL may match; with any allow rule, it must match one. */
+    allowRegex: RegExp[];
+    /** Regular expressions whose URLs are never recorded. */
+    ignoreRegex: RegExp[];
 }
-/** Builds the rules for configureApiTracking, with AppticsApiTracker.configure's names. */
+/**
+ * A URL as the rules compare it: `scheme://host[:port]/path`, the scheme and host lower-cased,
+ * the default port dropped, the query, fragment and a trailing slash removed. '' when it is not
+ * an absolute http(s) URL.
+ */
+export declare function ruleUrl(raw: string): string;
+/**
+ * Builds the rules configure takes. Each method may be called more than once, and takes any number
+ * of values: `new ApiTrackingBuilder().allowEquals(a, b).ignoreRegex(/x/).build()`.
+ */
 export declare class ApiTrackingBuilder {
     private rules;
-    /** Never records these hosts. */
-    ignoreDomains(...domains: string[]): this;
-    /** Records only these hosts; every other is skipped. */
-    allowOnlyDomains(...domains: string[]): this;
-    /** Records only hosts ending in these TLDs, e.g. `.com`. */
-    allowOnlyTLDs(...tlds: string[]): this;
-    /** Never records hosts ending in these TLDs, e.g. `.local`. */
-    ignoreTLDs(...tlds: string[]): this;
-    /** Never records hosts starting with these, e.g. `dev.`. */
-    ignoreDomainPrefixes(...prefixes: string[]): this;
-    /** Never records hosts ending with these, e.g. `.cdn.net`. */
-    ignoreDomainSuffixes(...suffixes: string[]): this;
-    /** Records the hosts a pattern such as `api.myapp.*` matches under that one name. */
-    groupDomains(...patterns: string[]): this;
-    /** Never records these paths: exact, `*` or `{name}` for one segment, `**` at the end for a prefix. */
-    ignoreEndpoint(...paths: string[]): this;
-    /** Records a path this pattern matches as the pattern, with each `{name}` as `*`. Tried before auto-detection. */
-    addPattern(...patterns: string[]): this;
-    /** Segments never turned into `*`, e.g. `v1` or `404`. */
-    preserveSegments(...segments: string[]): this;
-    /** `false`: only addPattern paths are normalized; every other path is recorded as it is. */
-    autoDetection(enabled: boolean): this;
+    /** Records only these URLs (and those any allowRegex matches): `https://api.example.com/orders`. */
+    allowEquals(...urls: string[]): this;
+    /** Never records these URLs: `https://api.example.com/health`. */
+    ignoreEquals(...urls: string[]): this;
+    /** Records only URLs these match (and those any allowEquals names): `/^https:\/\/api\.example\.com\//`. */
+    allowRegex(...patterns: Array<RegExp | string>): this;
+    /** Never records URLs these match: `/\/internal\//`. */
+    ignoreRegex(...patterns: Array<RegExp | string>): this;
     build(): ApiTrackingConfig;
 }
 /**
@@ -66,19 +38,12 @@ export declare class ApiTrackingBuilder {
 export declare function configureApiTracking(config: ApiTrackingConfig | ApiTrackingBuilder): void;
 /** The rules in force, for tests and the playground. */
 export declare function apiTrackingConfig(): ApiTrackingConfig;
-/** Whether calls to this host are recorded. Ignore rules are checked first and always win. */
-export declare function hostAllowed(hostname: string): boolean;
-/** The name a host is recorded under: the first groupDomains pattern it matches, or itself. */
-export declare function groupedHost(hostname: string): string;
-/** Whether a host is one of the groupDomains names, which carry a `*` no real host has. */
-export declare function isGroupedHost(hostname: string): boolean;
-/** The path without its query string or fragment, which is where ids and tokens travel. */
-export declare function withoutQuery(path: string): string;
-/** Whether ignoreEndpoint leaves this path out. Matched on the path as called, query removed. */
-export declare function endpointIgnored(path: string): boolean;
 /**
- * The path a call is recorded under. The query goes; then the first addPattern that matches is
- * used, with each `{name}` as `*` (the server's path rule has no room for braces); otherwise, with
- * autoDetection on, numeric ids, UUIDs and JWTs become `*`, except preserveSegments.
+ * Whether a call to `url` is recorded. Ignore rules are tried first and always win; then, when
+ * there are allow rules, the URL must match one. A URL that cannot be read is not recorded.
  */
+export declare function urlTracked(url: string): boolean;
+/** The path without its query string or fragment, which is where ids and tokens travel. */
+export declare function withoutQuery(path: string): string;
+/** The path a call is recorded under: the query goes, and numeric ids, UUIDs and JWTs become `*`. */
 export declare function normalizeApiPath(path: string): string;