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

package/CHANGELOG.md

@@ -0,0 +1,87 @@
+# Change Log
+
+# Apptics JS SDK 2.0.0-beta
+A rewrite of the web SDK in TypeScript, published on npm as ES modules, CommonJS and a minified browser build. Published under the `beta` npm tag; `latest` stays on 1.0.2. **`Apptics.init()` takes new config**: see "Upgrading from 1.0.2" in the README. Runs in Chrome 80+, Edge 80+, Firefox 74+ and Safari 14+.
+
+## Initialization
+- **The Android SDK's names**: `Apptics.init(config)`, `AppticsEvents.addEvent`, `AppticsScreenTracker.inScreen` / `outScreen`, `AppticsApiTracker.startTrackApi` / `endTrackApi` / `configure`, `AppticsLogger.enable` / `disable` / `isEnabled` / `v` / `d` / `i` / `w` / `e`, `AppticsTrackError`, `AppticsSetUser`, and `AppticsRemoteConfig`. The `<script>` build defines them as globals too. 1.0.2's `apptics.init`, `apptics.trackEvent`, `apptics.trackScreen`, `apptics.trackError` and `apptics.setUser` are gone, so code calling them has to be renamed.
+- **New config**: `Apptics.init()` takes `serviceUrl`, `zak`, `identifier` and `appversion`, all required. The SDK gets `aaid`, the portal id and the project id from the server, so `aaid`, `zsoid` and `projectID` are no longer passed in. A missing key is named in a console warning and `Apptics.init()` returns `false`.
+- **`appversion` is required**: 1.0.2 defaulted it to `1.0`, which attributed every session, error and crash to a version that was never shipped.
+- **`appversion` takes a string or a number**: `'2.4.0'`, `'v2.4-build512'` or a build number such as `512`. It is sent as text: a string is trimmed, and a number keeps 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 (`YOUR_APP_VERSION`, `YOUR_BUILD_OR_APP_VERSION`, `YOUR_APPVERSION`), is refused with a console warning and `Apptics.init()` returns `false`.
+- **`ready()`**: a Promise that resolves once the SDK is running. Calls made between `Apptics.init()` and that point are queued and replayed in order.
+- Calls that track or send something before `Apptics.init()` are ignored, and the first one logs a console warning saying so.
+- **`mute()` and `unmute()` are removed.** `setTrackingStatus(AP_TRACKING_STATUS.NO_TRACKING)` stops tracking, and unlike `mute()` it is stored across visits.
+- Safe to import during server-side rendering; nothing runs until `Apptics.init()` is called in the browser. Public calls never throw into the host app.
+- **Storage**: IndexedDB with a localStorage fallback. Data stored by 1.0.2 is migrated on the first visit. Queued items are stored one per record and a Web Lock keeps two tabs from sending the same data.
+
+## Packaging and CDN
+- **npm**: `import` and `require()` both work, with type declarations. Optional modules are separate entry points, so apps ship only what they use: `@zoho_apptics/apptics-js-sdk/feedback`, `/heatmap`, `/remote-config` and `/style.css`.
+- **One script tag**: the CDN builds (`apptics.min.js`, `feedback.esm.min.js`) load the feedback form's `style.css` themselves, so a page needs no separate `<link>`. `apptics.min.js` includes every module on `window.apptics`.
+- **License**: the Zoho Apptics JavaScript SDK license (see LICENSE) instead of MIT. It allows installing from npm or a CDN, bundling with your build tools and serving the SDK to your users as part of your web app.
+
+## Events
+- **Defined events, as on Android**: `AppticsEvents.addEvent(DefinedEvents.AP_USER_LOGIN, props?)` logs Apptics' ready-made events under their own `AP_` groups.
+- **`ap_` / `AP_` is reserved**: an app's event, group or property key starting with it is not logged.
+- **An event with an invalid group is not logged**, as on Android, instead of being filed under `default`; an event with no group is still `default`.
+- **Properties are judged one by one**: a bad key or an over-long value drops that property, and the event keeps the rest (it used to lose them all). Booleans are typed as Boolean and every number as Number (`1` and `0` were typed as Boolean); objects and arrays are sent as JSON text.
+
+## Sessions
+- **`track_session: false`** turns automatic sessions off, as Android's `automaticSessionsTrackingStatus = false`; events and screens are still recorded.
+
+## Screen Tracking
+- **`trackScreen()` is renamed `AppticsScreenTracker.inScreen()`**, as in the Android SDK: same arguments, and it returns the view's id for `AppticsScreenTracker.outScreen(id)`. `trackScreen` no longer exists, so 1.0.2 code calling it has to be renamed.
+- **Screen views have a duration.** A view ends when the next screen starts, when the page is hidden (coming back starts a new view), or when its session ends. `AppticsScreenTracker.inScreen()` now returns the view's id, and `AppticsScreenTracker.outScreen(id)` ends it yourself, as Android's `outScreen`. Until now every view was recorded with no time spent.
+- **Automatic screen tracking, on by default**: the first page and every navigation (`pushState`, `replaceState`, back and forward, `#/` hash routes) are recorded as screens, named by the path without its query string. A `AppticsScreenTracker.inScreen()` from the router names a route your own way. A `AppticsScreenTracker.inScreen()` call within 300 ms of a navigation — from a router hook — replaces the automatic view, so the navigation counts once under the app's name; `track_screen: false` turns automatic tracking off.
+- **`setScreenName()` is removed.** Records are attributed to the screen `AppticsScreenTracker.inScreen()` or automatic tracking last named; heatmap records with neither get the page's name, made from its path the same way.
+
+## Remote Logger
+- **`AppticsLogger`**: `AppticsLogger.v/d/i/w/e(tag, message, ...details)` sends the app's log lines to the Remote Logger page, as levels 1 to 5 in the Android and iOS order. Off until `AppticsLogger.enable()`; `AppticsLogger` in the `<script>` build. Each line carries the time it was logged and the function, file and line that logged it.
+- **Android's names too**: `AppticsLogger.v/d/i/w/e(tag, message)`, with the tag leading the message as `[tag]`, and `AppticsLogger.disable()`.
+- **`show_logs: true`** prints the app's lines to the browser console as well, as Android's `showLogs` does for Logcat.
+- **Offline storage is capped at 1 MB**, oldest lines dropped first, as on Android (instead of 200 lines).
+- **SDK diagnostics**: the SDK reports its own failures to the same page, tagged with the module it happened in. Off by default; `remote_log: true` turns it on, independently of `AppticsLogger`.
+
+## API Tracking
+- **Path normalization, as on Android**: numeric ids, UUIDs and JWTs in a path become `*`, and the query string is removed, so calls group by endpoint (`/users/42/orders` → `/users/*/orders`).
+- **`AppticsApiTracker.configure(new ApiTrackingBuilder()...build())`** with Android's rules: `ignoreDomains`, `allowOnlyDomains`, `allowOnlyTLDs`, `ignoreTLDs`, `ignoreDomainPrefixes`, `ignoreDomainSuffixes`, `groupDomains`, `ignoreEndpoint`, `addPattern`, `preserveSegments`, `autoDetection`. They apply to every call.
+- **`AppticsApiTracker.startTrackApi(url, method)` / `AppticsApiTracker.endTrackApi(id, code)`** time and record a call, as on Android.
+- **`track_api: true`** records every `fetch` and XHR call automatically (`enableApiTracking(on)` switches it later); a call is reported by hand with `AppticsApiTracker.startTrackApi` / `endTrackApi`. The SDK's own requests are never recorded. Host rules are set only through `AppticsApiTracker.configure`: the earlier `track_api_hosts` / `track_api_exclude_hosts` keys are gone, and `Apptics.init()` warns when it is given them.
+
+## Remote Config
+- **`AppticsRemoteConfig`** from `@zoho_apptics/apptics-js-sdk/remote-config` (`AppticsRemoteConfig` in the `<script>` build): four calls, as on Android: `fetchValue(name)` and `fetchValues({ name: default })` read parameters, `setCustomConditionValue` and `setFallbackWithOfflineValue` (below). The rule set is stored and resolved on the device, and conditions on the user re-apply on their own after `AppticsSetUser`.
+- **`setCustomConditionValue(key, value)`**, as on Android: conditions on a custom criteria match this device's value. Kept across visits; works before `Apptics.init()`.
+- **`fetchValue(name)`** and **`fetchValues({ name: default })`**, as on Android: Promises, with an optional callback. A parameter the console doesn't have is `null`.
+- **Fetched on start-up**, so values are this session's without the app asking.
+- **A fetch from the last five minutes is reused**; `coldFetch` asks the server regardless, at most three times a minute.
+- **`setFallbackWithOfflineValue(false)`**: a failed fetch answers with `null` and defaults instead of the values fetched before (the default).
+
+## Heatmap
+- **Every heatmap record has its screen view in `engagement/add`**: when nothing has named the screen (automatic screen tracking off, no `AppticsScreenTracker.inScreen()`), the first record on a page records a view of it, so the console can place the record.
+- **Heatmaps**: clicks (with rage and dead clicks) and scrolls, for the Apptics console. Off by default; `track_heatmap: true` plus an import of `@zoho_apptics/apptics-js-sdk/heatmap`. An element's visible text is used for its label only with `USAGE_TRACKING_WITH_PII`.
+
+## Debugging
+- **Debug mode**: `debug: true` in `Apptics.init()`, or `enableDebug()` / `disableDebug()` at any time, with or without `Apptics.init()`. Payloads go to the debug endpoints, for following in the Apptics web console. What the app sets with the functions wins over the `Apptics.init()` option; debug mode switches itself off after an hour with nothing tracked.
+- **`debug` now means debug mode.** The browser-console logging it turned on in 1.0.2 is `console_log: true`.
+
+## Feedback
+- **`sendFeedback()`** returns a Promise that resolves once the feedback is sent and rejects when it wasn't (SDK not started, offline, server refusal). It takes `includeLog` as a sixth argument; `includeLog` and `includeDyninfo` send their file when there is something stored, unless set to `false`.
+- `addFeedbackLog()` and `addDiagnosticsInfo()` are on the main entry point, so recording context doesn't pull the form into a bundle. `dyninfo.txt` carries the diagnostics and a `[Device Info]` block. Stored entries are capped at 1,000, and 10,000 characters per message.
+- The form works without the Quartz script; the screen-recording option is hidden instead.
+
+## Server APIs
+- Every call goes to the v2 APIs. Logs are sent in batches, and the server's per-module settings (`getsdkconfig`) are honoured: a module the server switches off stops recording and sending.
+
+## Fixes (2.0.0-beta)
+- Queued engagements, errors and heatmap records are removed only once the server accepts them; a failed send (5xx, timeout, CORS, dropped connection) goes again instead of being lost.
+- Page-close sends stay within the browser's 64 KiB keepalive limit; a larger batch is kept for the next visit.
+- The flush timer never sent errors; engagements, errors and heatmaps now go out in turn.
+- The server's "stop tracking" signal was ignored.
+- `ignore_do_not_track: true` disabled tracking instead of ignoring the browser's Do Not Track setting.
+- Click tracking with `apeventaction` required jQuery.
+- The feedback form crashed without Quartz; the SDK crashed without `screen.orientation`.
+- Send timers multiplied on every reconnect; devices were registered twice; the device update on an app-version change was sent empty.
+- A successful error send wiped errors recorded while it was in flight.
+- Requests now time out after 30 seconds, and ids in request URLs are encoded.
+
+# Apptics JS SDK 1.0.2
+- First releases on npm (1.0.0, 1.0.1 and 1.0.2, August 2025). The SDK ran alongside the Apptics console snippet and exported nothing for `import` or `require()`.

package/LICENSE

@@ -0,0 +1,13 @@
+Copyright (c) 2025 Zoho Corporation Private Limited
+
+Zoho grants you a limited, revocable, non-exclusive, non-sublicensable license to copy, install and use the Zoho Apptics JavaScript SDK (the "SDK") solely in connection with your use of Zoho Apptics in your websites and web applications. This license includes the right to:
+(a) install the SDK from a package registry such as npm, or load it from a content delivery network;
+(b) bundle, transpile, minify or otherwise process the SDK with your web application's build tools; and
+(c) serve the SDK, processed only as described in (b), to your end users' browsers as part of your website or web application.
+
+You will not:
+(i) modify, adapt, translate or otherwise create derivative works of the SDK, except as permitted in (b);
+(ii) reverse engineer, deobfuscate, decompile, disassemble or otherwise attempt to discover the source code of the SDK;
+(iii) rent, sell, assign, sublicense or otherwise transfer rights in the SDK, or distribute it other than as part of your website or web application as permitted in (c);
+(iv) remove any proprietary notices or licenses from the SDK; or
+(v) use, post, publish, transmit or introduce any device, software or routine that interferes or attempts to interfere with the operation of the SDK or of Zoho Apptics.