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

package/dist/cjs/remotelogger/index.js

@@ -0,0 +1,18 @@
+/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta.1 | (c) Zoho Corporation Private Limited | see LICENSE */
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var logger = require('../remotelog/logger.js');
+
+/**
+ * The app logger, shipped as its own entry point:
+ *   import { AppticsLogger } from '@zoho_apptics/apptics-js-sdk/remote-logger';
+ *
+ * AppticsLogger: verbose / debug / info / warn / error(message, props?), shown on the
+ * console's Remote Logger page. A line is recorded as it is written, with no switch to turn on.
+ * Apps that don't import it don't ship it.
+ */
+
+exports.AppticsLogger = logger.AppticsLogger;
+exports.default = logger.AppticsLogger;

package/dist/cjs/scheduler.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Sends everything queued now. With `forget`, the requests are sent without waiting for a
+ * response (page hide), so they survive the page going away.
+ */
+export declare function flush(forget?: boolean): Promise<void>;
+/** Starts the flush and getupdates intervals once; later calls do nothing until stopTimers(). */
+export declare function startTimers(): void;
+export declare function stopTimers(): void;

package/dist/cjs/scheduler.js

@@ -0,0 +1,78 @@
+/*! @zoho_apptics/apptics-js-sdk v2.0.0-beta.1 | (c) Zoho Corporation Private Limited | see LICENSE */
+'use strict';
+
+var state = require('./core/state.js');
+var utils = require('./core/utils.js');
+var logger = require('./core/logger.js');
+var consent = require('./core/consent.js');
+var batch = require('./core/batch.js');
+var send = require('./engagement/send.js');
+var send$1 = require('./errors/send.js');
+var hooks = require('./core/hooks.js');
+var index = require('./device/index.js');
+var debug = require('./core/debug.js');
+
+/**
+ * Sends everything queued now. With `forget`, the requests are sent without waiting for a
+ * response (page hide), so they survive the page going away.
+ */
+function flush(forget) {
+    if (!consent.canTrack('flush')) { // no i18n
+        return Promise.resolve();
+    }
+    state._ZAP._sending = false;
+    // one after the other: sending both at once makes the second wait for the 500 ms retry
+    return send.sendEngagementData(forget).then(function () {
+        return send$1.sendErrorData(forget);
+    }).then(function () {
+        // the hook heatmap/send.ts sets
+        return hooks.hooks.sendHeatmaps(forget);
+    });
+}
+var sendingInterval = null;
+var getUpdatesInterval = null;
+/** Starts the flush and getupdates intervals once; later calls do nothing until stopTimers(). */
+function startTimers() {
+    if (sendingInterval === null) {
+        sendingInterval = setInterval(function () {
+            // the only tick that happens whether or not anything is being tracked, which is
+            // exactly the case debug mode has to expire in
+            debug.expireDebugIfIdle();
+            logger.Console.log('scheduleToSendDataToServer: Scheduling to send engagement data to the server after sometime'); // no i18n
+            // one after the other, as flush() does: run together, the second and third find the
+            // first still sending and are deferred, and the third's retry replaces the second's
+            send.sendEngagementData().then(function () {
+                return send$1.sendErrorData();
+            }).then(function () {
+                return hooks.hooks.sendHeatmaps();
+            });
+        }, state.getConfig('batch_flush_interval')); // no i18n
+    }
+    if (getUpdatesInterval === null) {
+        // the interval is the floor, not the schedule: getsdkconfig answers with next_check_after,
+        // and asking again before then is a call the server has already told us it will not answer
+        // differently. The timer still ticks so a server that sends no hint behaves as before.
+        getUpdatesInterval = setInterval(function () {
+            if (state._ZAP._nextConfigCheck > 0 && utils.nowMs() < state._ZAP._nextConfigCheck) {
+                return;
+            }
+            logger.Console.log('scheduleToGetUpdatesFromServer: asking the server for its config'); // no i18n
+            index.getUpdatesFromServer().catch(function (err) {
+                logger.Console.log(err);
+            });
+        }, state.getConfig('getupdates_interval')); // no i18n
+    }
+}
+function stopTimers() {
+    if (sendingInterval !== null)
+        clearInterval(sendingInterval);
+    if (getUpdatesInterval !== null)
+        clearInterval(getUpdatesInterval);
+    sendingInterval = null;
+    getUpdatesInterval = null;
+    batch.clearDefer();
+}
+
+exports.flush = flush;
+exports.startTimers = startTimers;
+exports.stopTimers = stopTimers;

package/dist/cjs/types.d.ts

@@ -0,0 +1,385 @@
+import type { AP_FEEDBACK_TYPE, AP_TRACKING_STATUS } from './core/constants.js';
+import type { UserBuilder } from './user/index.js';
+import type { ApiTrackingBuilder, ApiTrackingConfig } from './engagement/api-rules.js';
+import type { DefinedEvent, DefinedEvents } from './engagement/defined-events.js';
+/** One entry of screen_routes: a route pattern, or an exact path or a regular expression with the name to record. */
+export type ScreenRoute = string | {
+    equals: string;
+    name: string;
+} | {
+    regex: RegExp | string;
+    name: string;
+};
+/** Loose record for legacy payloads and server JSON that are built and sent as-is. */
+export type Dict = Record<string, any>;
+/** An item in the engagement or error queue. */
+export interface QueueItem {
+    id?: string;
+    type?: string;
+    starttime?: number;
+    endtime?: number;
+    [key: string]: any;
+}
+/** Device properties sent to and returned by `device/add`. */
+export type DeviceInfo = Dict;
+export interface UserInfo {
+    userid?: string;
+    groupid?: string;
+    status?: number;
+    [key: string]: any;
+}
+export interface ServerResult<T = Dict> {
+    result: string;
+    data?: T;
+    error_code?: unknown;
+    [key: string]: any;
+}
+export type TrackingStatus = (typeof AP_TRACKING_STATUS)[keyof typeof AP_TRACKING_STATUS];
+export type FeedbackType = (typeof AP_FEEDBACK_TYPE)[keyof typeof AP_FEEDBACK_TYPE];
+export type Properties = Record<string, unknown>;
+/** The config init() requires. The console snippet provides the same shape as window.appticssettings._defaultoptions. */
+export interface AppticsConfig {
+    /** Apptics host every request goes to, e.g. https://apptics.zoho.com (a trailing slash is ignored). Was `serviceUrl`. */
+    base_url: string;
+    /** The app's key from the console, sent as the `zak` header on app/addversion and device registration. Was `zak`. */
+    auth_key: string;
+    /** The app's domain as registered in the console, e.g. com.zoho.web.zylker. Was `identifier`. */
+    app_domain: string;
+    /**
+     * Your app's version or build number, e.g. '2.4.0' or 512. Required: everything the SDK reports
+     * is only meaningful against the build it came from, so there is no default. Changing it
+     * registers the new version. Sent as text: a string is trimmed, and a number keeps only the
+     * digits JavaScript gives it (1.10 is '1.1'), so pass a dotted version as a string. A blank
+     * value, or a snippet placeholder such as 'YOUR_APP_VERSION', is refused.
+     */
+    appversion: string | number;
+    /** @deprecated ignored: app/addversion answers with the aaid */
+    aaid?: string;
+    /** @deprecated ignored: app/addversion answers with the aaid */
+    aaID?: string;
+    /** @deprecated ignored: app/addversion answers with the portal id */
+    zsoid?: string;
+    /** @deprecated ignored: app/addversion answers with the project id */
+    projectID?: string;
+    /** @deprecated 1.x console-snippet name for base_url: still read, with a warning */
+    base_domain?: string;
+    /** @deprecated 1.x console-snippet name for auth_key: still read, with a warning */
+    token?: string;
+    /**
+     * Debug mode: send engagement, exception and log payloads to their `debug/` twins, which answer
+     * with a request id and a link to the server's own logs, for following in the Apptics web
+     * console. Off by default; it does not change what is sent. Same as calling enableDebug().
+     */
+    debug?: boolean;
+    /** Log the SDK's own activity to the browser console. Off by default. */
+    console_log?: boolean;
+    ignore_do_not_track?: boolean;
+    /**
+     * Record the app's API calls automatically, by wrapping XHR and fetch. Off by default. The SDK's
+     * own requests are never recorded. Which hosts and endpoints are recorded, and under what path,
+     * is set with AppticsApi.configure(new AppticsApi.ApiTrackingBuilder()...build()).
+     */
+    track_api?: boolean;
+    /**
+     * Record screen views automatically: the page the SDK starts on, then every navigation —
+     * history.pushState / replaceState, back and forward, and `#/` hash routes. The screen is named
+     * by its path, without the query string. On by default. A inScreen() call within 300 ms of a
+     * navigation replaces its automatic view; set this false to track only the app's own calls.
+     */
+    track_screen?: boolean;
+    /**
+     * How automatic screen tracking names a path, tried in order; the first that matches wins, and a
+     * path none matches keeps its own name. Each entry is one of:
+     * - a route pattern, `'/users/{id}/orders'`: `{name}`, `:name` and `*` each match one segment,
+     *   recorded as a star, so `/users/42/orders` and `/users/43/orders` are one screen;
+     * - `{ equals: '/', name: 'Home' }`: that path exactly;
+     * - `{ regex: /^\/orders\/\d+$/, name: 'Order detail' }`: any path the regular expression matches.
+     * Paths are matched without their query string.
+     */
+    screen_routes?: ScreenRoute[];
+    /**
+     * The feedback form's theme: 'light', 'dark', or 'auto' (the default) to follow the visitor's
+     * system setting. The colors are CSS variables on the form (`--zasdk-primary-color` and the rest
+     * of the `--zasdk-*` set), which a page may override.
+     */
+    feedback_theme?: 'light' | 'dark' | 'auto';
+    /** How often queued data is sent, in milliseconds. Default 30000, at least 1000. */
+    batch_flush_interval?: number;
+    /** How often the server's tracking flags are fetched, in milliseconds. Default 120000, at least 10000. */
+    getupdates_interval?: number;
+    /** Most items in one batch. Default 50, between 1 and 500. */
+    batch_size?: number;
+    /** Days an unsent item is kept before it is dropped. Default 7, between 1 and 30. */
+    batch_request_timeout?: number;
+    /** Idle minutes that end a session. Default 30, between 1 and 1440. */
+    inactiveduration?: number;
+    /**
+     * How long a visit must last before its session is recorded, in milliseconds. Default 5000, at
+     * most 60000. A shorter visit with nothing tracked in it is not reported at all; anything tracked
+     * inside the window records the session at once, with its real start time. 0 turns the wait off.
+     */
+    min_session_duration?: number;
+    /**
+     * Record where people click and how far they scroll. Off by default; AppticsHeatmap.trackHeatmap()
+     * switches it later.
+     */
+    track_heatmap?: boolean;
+    /** Most heatmap records one visit may produce. Default 500; capture pauses past it. */
+    heatmap_max_per_session?: number;
+    /** @deprecated the earlier name for `debug` (debug mode); `debug` wins when both are given */
+    debug_api?: boolean;
+    /**
+     * What to call this device in the debug stream, e.g. 'QA iPad 3'. Sent on engagement,
+     * exception and log, the three endpoints that declare it. Unset, nothing is sent unless
+     * debug mode is on, where a label is derived from the browser and OS instead.
+     */
+    device_name?: string;
+    [key: string]: unknown;
+}
+export interface UserValidationResult {
+    data: Record<string, string | number | boolean>;
+    datatype: Record<string, 'String' | 'Number' | 'Boolean'>;
+    message: Array<{
+        code: 101 | 102 | 103 | 104;
+        keys: string[];
+    }>;
+}
+/**
+ * Screen recording in the feedback form, as getsdkconfig's `quartz` block sets it up:
+ *   { quartz_enabled, quartz_workspace, quartz_department, quartz_domain, quartz_cdn_url }
+ * The app passes none of it; the console's settings for the app decide.
+ */
+export interface QuartzSettings {
+    enabled: boolean;
+    /** quartz_workspace: the workspace the recording is filed under. */
+    workspace: string;
+    /** quartz_department: the department within it. */
+    department: string;
+    /** quartz_domain, e.g. zoho.com: recordings go to https://quartz.<domain>. */
+    domain: string;
+    /**
+     * quartz_cdn_url: the Quartz script, loaded by the SDK when the form needs it. When the answer
+     * has none, the SDK uses Zoho's CDN for the serviceUrl (static.localzohocdn.com for localzoho,
+     * static.zohocdn.com otherwise).
+     */
+    cdnUrl: string;
+}
+export interface QuartzApi {
+    startRecording(details: {
+        workspaceLinkName: string;
+        departmentLinkName: string;
+        recordingDomain: string;
+    }): void;
+    previewVideo(): void;
+    editVideo(options: {
+        quartzBranding: boolean;
+    }): void;
+    clearFeedback(): void;
+    endRecording(): void;
+    setVideoContent(element: Element | null): void;
+    submitRecording(details: {
+        email: string;
+        subject: string;
+    }): Promise<{
+        feedbackLink?: string;
+    } | undefined>;
+}
+export interface QuartzConstantsApi {
+    ErrorType: Record<string, string>;
+    FeedbackState: Record<string, string>;
+}
+/**
+ * One heatmap record: a click or a finished scroll gesture, as `heatmap/add` takes it.
+ *
+ * Web-shaped. The endpoint's mobile fields have no meaning in a browser and are not sent:
+ * `battery_in`/`battery_out` (the Battery Status API is gone from Firefox and never existed in
+ * Safari), `pressure` and `finger_count` (0 and 1 for any mouse), `service_provider` (a carrier
+ * name, which the web has no access to). Sending constants for them would put dead columns in
+ * every record.
+ */
+export interface HeatmapRecord {
+    /** Queue key; removed before the record is sent. */
+    id?: string;
+    session_start_time: number;
+    /** When this record happened. The only thing that orders records inside a session. */
+    triggered_time: number;
+    screen: string;
+    url_path: string;
+    /**
+     * 'buttonclick' for a click on something clickable, 'default' otherwise. The server accepts
+     * only `event|default|buttonclick`; the kind of movement goes in `gesture_type`.
+     */
+    triggered_type: 'event' | 'default' | 'buttonclick';
+    /** 'click', or 'up-scroll' / 'down-scroll' / 'left-scroll' / 'right-scroll'. */
+    gesture_type: string;
+    /** Milliseconds the gesture took. 0 for a click. */
+    gesture_duration: number;
+    /** 'mouse', 'touch' or 'pen' from the pointer event. Absent for a scroll, which has none. */
+    input_type?: string;
+    /** A name for the element: an author's attribute where there is one, its text only with PII consent. */
+    element_label: string;
+    /** A stable number for the element's position in the tree, so clicks on one control group together. */
+    triggered_id: number;
+    coordinate_x: number;
+    coordinate_y: number;
+    /** 0-1 across the viewport width. */
+    normalized_x: number;
+    /** 0-1 down the full page height, which is what a scroll-depth map reads. */
+    normalized_y: number;
+    scroll_offset_x: number;
+    scroll_offset_y: number;
+    screen_width: number;
+    screen_height: number;
+    content_height: number;
+    orientation: number;
+    network_status: number;
+    edge_type: string;
+    /** Pixels per second, x1000. 0 for a click. */
+    velocity: number;
+    is_clickable: 0 | 1;
+    is_rage_click: 0 | 1;
+    is_dead_click: 0 | 1;
+}
+/** What `AppticsError.trackError` accepts: a window `error` / `unhandledrejection` event or the same shape. */
+export type ErrorLike = Event | {
+    type?: string;
+    error?: unknown;
+    reason?: unknown;
+};
+/** What sendFeedback() sends. Every key is optional. */
+export interface SendFeedbackOptions {
+    /** AppticsFeedback.AP_FEEDBACK_TYPE: BUG (0), FEEDBACK (1, the default), HELP (2), REPORT (3). */
+    type?: FeedbackType;
+    /** The feedback's text. */
+    message?: string;
+    /** Files to attach: at most 5, 10 MB in all. */
+    attachments?: FileList | File[] | null;
+    /** Log files of the app's own to send along. */
+    logFiles?: FileList | File[] | null;
+    /** The addDiagnosticsInfo() entries and the device's details: unset sends them when there are entries waiting. */
+    includeDiagnostics?: boolean;
+    /** The addFeedbackLog() lines: unset sends them when there are any, false never does. */
+    includeLog?: boolean;
+    /** Sends it from nobody. Unset, it is from the active user AppticsUser.setUser registered. */
+    isAnonymous?: boolean;
+}
+/** What feedbackFormOpen() fills the form in with. Every key is optional. */
+export interface FeedbackOpenOptions {
+    /** The tab the form opens on: AppticsFeedback.AP_FEEDBACK_TYPE.BUG, FEEDBACK, HELP or REPORT. */
+    type?: FeedbackType;
+    /** Text already in the description. */
+    message?: string;
+    /** Starts the logs toggle on. */
+    includeLog?: boolean;
+    /** Starts the diagnostics toggle on. */
+    includeDiagnostics?: boolean;
+    /** Files already attached: at most 5, 10 MB in all. */
+    attachments?: FileList | File[] | null;
+    /** Log files of the app's own already attached. */
+    logFiles?: FileList | File[] | null;
+    /** Starts the user picker on Anonymous, even with a user registered. */
+    isAnonymous?: boolean;
+}
+/** The optional feedback modal, from '@zoho_apptics/apptics-js-sdk/feedback'. */
+export interface AppticsFeedbackApi {
+    /**
+     * Sends feedback without the form. Resolves once it is sent; rejects when it wasn't: the SDK
+     * has not started (no init()), the browser is offline, or the server refused it.
+     */
+    sendFeedback(options?: SendFeedbackOptions): Promise<void>;
+    /** Opens the form, filled in with `options` when they are given. */
+    feedbackFormOpen(options?: FeedbackOpenOptions): void;
+    feedbackFormClose(): void;
+    /** The feedback types: BUG, FEEDBACK, HELP, REPORT. */
+    AP_FEEDBACK_TYPE: typeof AP_FEEDBACK_TYPE;
+    /** Records a timestamped line, sent as feedbacklog.txt with the next feedback submission. */
+    addFeedbackLog(message: string): void;
+    /** Records a diagnostics key/value under `heading`, sent inside dyninfo.txt with the next feedback. */
+    addDiagnosticsInfo(heading: string, key: string, value: unknown): void;
+    /**
+     * The form's theme from now on, restyling one open now: 'light', 'dark', or 'auto' to follow
+     * the visitor's system setting. For a page with its own theme switch, called as it changes.
+     */
+    setFeedbackTheme(theme: 'light' | 'dark' | 'auto'): void;
+}
+export interface AppticsSdk {
+    /** Android's Apptics: starting the SDK, and what applies to all of it. */
+    Apptics: {
+        /** Starts the SDK. The config object is required; the console snippet supplies it via auto-init. */
+        init(config: AppticsConfig): boolean;
+        /** Resolves true once start-up (storage load, device, session) has finished; false if it can't start. */
+        ready(): Promise<boolean>;
+        /** Sends stored engagements, errors and heatmap records now; resolves once they have gone out. */
+        flush(): Promise<void>;
+        /** Clears stored identity, queued data and remote config values, then starts again. */
+        reset(): void;
+        /**
+         * Turns debug mode on, before or after Apptics.init(). Engagement, exception and log then go to
+         * their `debug/` twins, whose answers carry a request id and a link into the server's own logs. It
+         * switches itself off after an hour with nothing tracked.
+         */
+        enableDebug(): void;
+        /** Turns debug mode off, before or after Apptics.init(); wins over `debug` in init(). */
+        disableDebug(): void;
+    };
+    /** Android's AppticsEvents. */
+    AppticsEvent: {
+        /** Apptics' defined events, as Android's DefinedEvents, to log with addEvent. */
+        DefinedEvents: typeof DefinedEvents;
+        /** An event. An invalid name or group is not logged; a group left out is `default`. */
+        addEvent(eventName: string, groupName?: string, properties?: Properties): void;
+        /** A defined event (AppticsEvent.DefinedEvents.AP_USER_LOGIN, …), which brings its own group. */
+        addEvent(definedEvent: DefinedEvent, properties?: Properties): void;
+    };
+    /** Android's AppticsScreenTracker. */
+    AppticsScreen: {
+        /** Records a screen view and returns its id, for outScreen; '' for an invalid name. */
+        inScreen(screenName: string, properties?: Properties): string;
+        /** Ends the screen view inScreen began, before the next screen would. */
+        outScreen(id: string): void;
+    };
+    /** Android's AppticsApiTracker. */
+    AppticsApi: {
+        /** Builds the rules configure takes: `new AppticsApi.ApiTrackingBuilder()…build()`. */
+        ApiTrackingBuilder: typeof ApiTrackingBuilder;
+        /** Begins timing one call; returns the id endTrackApi takes. */
+        startTrackApi(url: string, method?: string): string;
+        /** Finishes the call startTrackApi began, and records it. */
+        endTrackApi(id: string, responseCode: number, responseMessage?: string): void;
+        /** The rules API tracking records by, from ApiTrackingBuilder. Works before Apptics.init(). */
+        configure(config: ApiTrackingConfig | ApiTrackingBuilder): void;
+        /**
+         * Turns automatic API tracking on or off after Apptics.init(). Equivalent to the `track_api`
+         * config flag, which is the usual way to set it.
+         */
+        enableApiTracking(enabled?: boolean): void;
+    };
+    /** Errors the app caught, and the switch for tracking uncaught ones. */
+    AppticsError: {
+        /** Reports an error the app caught, or an `error` / `unhandledrejection` event. */
+        trackError(error: ErrorLike, properties?: Properties): void;
+        /** Turns the automatic tracking of uncaught errors and unhandled rejections on or off. */
+        trackGlobalErrorHandler(enabled?: boolean): void;
+    };
+    /** Android's AppticsUser. */
+    AppticsUser: {
+        /** Registers the signed-in user. Properties may be a plain object, or the result of UserBuilder.build(). */
+        setUser(userid: string, groupid?: string, properties?: Properties | UserValidationResult): void;
+        /** The registered user, or {} when there is none. */
+        getUser(): UserInfo;
+        /** Builds the user's properties for setUser. */
+        UserBuilder: typeof UserBuilder;
+    };
+    /** Click and scroll capture for the console's heatmaps. */
+    AppticsHeatmap: {
+        /** Starts or stops recording clicks and scrolls; `on` defaults to true. */
+        trackHeatmap(on?: boolean): void;
+    };
+    /** Android's AppticsSettings: what the SDK may track for this visitor. */
+    AppticsSettings: {
+        /** The states setTrackingStatus takes. */
+        AP_TRACKING_STATUS: typeof AP_TRACKING_STATUS;
+        setTrackingStatus(status: TrackingStatus): void;
+        getTrackingStatus(): TrackingStatus;
+    };
+}

package/dist/cjs/user/index.d.ts

@@ -0,0 +1,33 @@
+import type { Dict, Properties, UserInfo, UserValidationResult } from '../types.js';
+export declare function getUser(): UserInfo;
+export declare function setUser(userid?: string, groupid?: string, jsonObj?: Properties | UserValidationResult): void;
+export declare function addOrUpdateUser(user_info: Dict): void;
+export declare function getUserInfo(): void;
+export declare function registerUserWithApptics(user_info: Dict): Promise<Dict>;
+/** Builds validated user properties for setUser. */
+export declare class UserBuilder {
+    [key: string]: unknown;
+    setFirstName(first_name: string): this;
+    setLastName(last_name: string): this;
+    setCompanyName(company_name: string): this;
+    setEmailAddress(email_address: string): this;
+    setContactNumber(contact_number: string): this;
+    setCountry(country: string): this;
+    setRegion(region: string): this;
+    setCity(city: string): this;
+    setGeoLocation(geo_location: string): this;
+    setGender(gender: string): this;
+    setPlanType(plan_type: string): this;
+    setTimezone(timezone: string): this;
+    setLanguage(language: string): this;
+    setEngagementScore(engagement_score: number): this;
+    setDateOfBirth(date_of_birth: number): this;
+    addStringProperty(key: string, value: string): this;
+    addBooleanProperty(key: string, value: boolean): this;
+    addNumberProperty(key: string, value: number): this;
+    setCustomProperties(obj: Record<string, unknown>): this;
+    build(): UserValidationResult;
+}
+export declare const users: {
+    UserBuilder: typeof UserBuilder;
+};