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

package/CHANGELOG.md

@@ -1,5 +1,69 @@
 # Change Log
 
+# Apptics JS SDK 2.0.0-beta.2
+Published under the `beta` npm tag; `latest` stays on 1.0.2. **Fixes heatmaps for npm apps**: with 2.0.0-beta.1 from npm, heatmap records were captured but never sent. **Breaking: an event's group is required.** **New: every automatic tracker switched the same way: a config key and a `set…Tracking()` call, and each kind of engagement follows its own switch in the Apptics console.**
+
+## Switching automatic tracking: a config key and a set…Tracking() call each
+- New config keys: `track_error` (uncaught errors and unhandled rejections, on by default) and `track_click` (clicks on elements tagged `apeventaction`, on by default), beside `track_screen`, `track_api` and `track_heatmap`.
+- New calls: `AppticsEvent.setClickTracking(enabled?)` and `AppticsScreen.setScreenTracking(enabled?)`.
+- Renamed, so all five read the same: `AppticsApi.enableApiTracking` is `AppticsApi.setApiTracking`, `AppticsError.trackGlobalErrorHandler` is `AppticsError.setErrorTracking`, and `AppticsHeatmap.trackHeatmap` is `AppticsHeatmap.setHeatmapTracking`. The earlier names still work, with a console warning naming the call to use, once per page.
+- Each call takes `true` or `false`, `true` when left out. The config key decides at start-up: a call made before `Apptics.init()` is replaced by it, and `Apptics.reset()` goes back to it. Before, `trackGlobalErrorHandler(false)` called before `Apptics.init()` stayed in force; now `track_error: false` is the way to start with it off.
+- The calls the app makes itself (`addEvent`, `inScreen`, `trackError`, `startTrackApi`) record whichever way a switch is set.
+
+## Each kind of engagement follows its own module in getsdkconfig
+- Events (module 5), API calls (6), screens (10) and sessions (11) are each switched by their own module. 2.0.0-beta.1 read only sessions (11) and switched all four with it, so turning off one kind in the Apptics console stopped them all, and turning off events alone did nothing.
+- A kind that is off is not recorded, and the console says so in debug mode. Items of that kind already queued stay until it is on again, or until they expire (`batch_request_timeout`, 7 days).
+- With sessions off and events or screens on, events and screens are still recorded, each with its session's start time; only the session itself is not sent.
+- Errors follow `js_error` (module 15), the web SDK's own. 2.0.0-beta.1 read `crash` (13), which belongs to the native SDKs.
+- A module the server does not mention is on, as before. Settings stored by an earlier build, with one `engagementtracking` flag, still switch all four.
+
+## An event's group is required
+- Breaking: `AppticsEvent.addEvent(eventName, groupName, properties?)` needs a group. An event without one (left out, `''` or `null`) is not logged, and the console says so, debug or not: `AppticsEvent.addEvent: groupName is required for "<event>": addEvent(eventName, groupName, properties?)`, once per event name. 2.0.0-beta.1 filed it under `default`, a group the app never named.
+- `addEvent(eventName, properties)`, with the properties in the group's place, is refused the same way.
+- Click tracking: an element with `apeventaction` and no `apgroupaction` around it is not tracked, and the console says the group is missing. 2.0.0-beta.1 filed it under `default`.
+- Defined events (`AppticsEvent.DefinedEvents.X`) bring their own group, as before. An invalid group is still refused, as before.
+- TypeScript: `groupName` is required in `addEvent`'s types, so a call without it is a compile error.
+
+## Heatmaps are sent from npm builds
+- Fix: with the npm package, heatmap records were captured and stored but never sent, by the flush timer or by `Apptics.flush()`. The sender was wired up by a module imported only for its side effect, and since the package's `sideEffects` names only the CDN bundle, app bundlers (Vite, webpack, Rollup) left it out. The CDN `<script>` build was not affected. A test now bundles the main entry the way an app does and checks that the sender is kept.
+
+## Sessions end when the user left
+- When a tab goes inactive (hidden, minimised, or its window loses focus to another one), that moment is the session's `lastactivetime`. Focus moving into an iframe on the page does not count.
+- Back within `inactiveduration` (30 minutes by default), the same session goes on.
+- Not back by then, the session ends at `lastactivetime` and is sent straight away, rather than staying open until the user returns or the tab closes. Coming back later starts a new session.
+- A tab closed while inactive ends its session at `lastactivetime`, not when it closed: the time it sat hidden is no longer session time. A tab closed while in use ends it then, as before.
+- While another tab of the site is on the same session, a tab that goes inactive or closes only leaves it; the last one ends it.
+
+## The server's settings (getsdkconfig) are read on the server's schedule
+- Once per page load: after `device/add` on a first visit, after `app/addversion` on a returning one (2.0.0-beta.1 made a returning visit wait for the first timer tick).
+- Then at the time the answer's `next_check_after` gives, instead of every `getupdates_interval`. `getupdates_interval` is the wait only when an answer gives no time.
+- Coming back to the tab asks again only once that time has passed; switching tabs used to ask every time.
+- A device registered again during a page load (new device details, or a new SDK build) no longer asks a second time.
+
+## Remote config stays up to date by itself
+- The first fetch of each page load sends `flagtime` 0 and gets the whole rule set, which replaces what was stored.
+- After that the SDK asks every 3 minutes, and when the tab comes back after 15 seconds or more away, with `flagtime` set to the time of its last answered fetch. The server answers with only what changed, which is merged into the stored set by `paramid` and `conditionid`; parameters and conditions it does not resend are kept.
+- The five-minute cache is removed: `fetchValue` and `fetchValues` answer from the values the polling keeps up to date, without a request of their own.
+- **`coldFetch` is back**, as the last argument of `fetchValue(name, callback?, coldFetch?)` and `fetchValues(names?, callback?, coldFetch?)`, `false` by default; it may take the callback's place (`fetchValue(name, true)`, `fetchValues(true)`). `true` asks the server for the whole rule set now (`flagtime` 0), replaces the stored set with it and answers from it. At most three a minute; one past that answers from the values the page already has.
+
+## Apptics.flush() sends at most once every 15 seconds
+- `Apptics.flush()` called by an app, or from the browser console, sends at most once every 15 seconds. A call sooner than that sends nothing and resolves at once; what is stored goes with the next send. The SDK's own sends (the flush timer, page hide and close, back online) are not held to it.
+
+## Stored data follows the app it belongs to
+- A page that starts with a different `base_url`, `app_domain` or `auth_key` from the stored data's clears everything the SDK stored (settings and all five queues, unsent data included) before start-up, which then runs as on a first visit: `app/addversion`, `device/add` and the rest. 2.0.0-beta.1 compared only `base_url` and `app_domain`, and kept the heatmap, remote logger and feedback log queues.
+- `app_version_info` keeps an 8-character fingerprint of `auth_key` (`zakhash`), not the key itself. Data stored by 2.0.0-beta.1, which has none, registers the app version again once and is not cleared.
+- `Apptics.reset()` empties the heatmap, remote logger and feedback log queues too.
+
+## The CDN build is served from static.zohocdn.com
+- `https://static.zohocdn.com/apptics-js-sdk/{version}/apptics.min.js`, with `apptics.esm.min.js`, `feedback.esm.min.js`, `chunks/` and the source maps in the same folder. Each release has a folder of its own.
+- Remote config and the remote logger have module files of their own, as on npm: `remoteconfig.esm.min.js` (`AppticsRemoteConfig`) and `remotelogger.esm.min.js` (`AppticsLogger`), beside `apptics.esm.min.js` and `feedback.esm.min.js`. A page imports only the ones it uses, and they share one copy of the SDK.
+- `npm run build` also writes that layout to `cdn/{version}/`, and the build server (`npm run build:cdn`, which registers the version first) zips it as `{version}/…` with `dist-meta.json`.
+
+## Fixes
+- `device/add` sends `isanonrequired=false`. The web SDK has no anonymous mode, only the tracking statuses (with PII, without PII, none), which `devicestatus` carries; with the default status, usage tracking without PII, 2.0.0-beta.1 sent `true`.
+- The device was registered again (`device/add`) on every page load when the server's answer carried no `anonymousid`, as sdk-apptics.zoho.in's does. A device with a `deviceid` counts as registered; `anonymousid` is optional.
+- Start-up waits for stored data of another app to be cleared before calling `app/addversion`.
+
 # Apptics JS SDK 2.0.0-beta.1
 Published under the `beta` npm tag; `latest` stays on 1.0.2. **Breaking for 2.0.0-beta code**: the changes are listed below, each with what to use instead.
 
@@ -111,7 +175,7 @@ Breaking for 2.0.0-beta code: each call keeps its name and moves onto the object
 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 "Migrating from 1.0.2 to 2.0.0-beta.1" 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 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`.
@@ -127,37 +191,37 @@ A rewrite of the web SDK in TypeScript, published on npm as ES modules, CommonJS
 - **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.
+- **Defined events**: `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`.
+- **An event with an invalid group is not logged**, 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.
+- **`track_session: false`** turns automatic sessions off; 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.
+- **`trackScreen()` is renamed `AppticsScreenTracker.inScreen()`**: 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. 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).
+- **`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. 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.
+- **Tagged lines**: `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.
+- **Offline storage is capped at 1 MB**, oldest lines dropped first (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.
+- **Path normalization**: 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 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.
 - **`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`.
+- **`AppticsRemoteConfig`** from `@zoho_apptics/apptics-js-sdk/remote-config` (`AppticsRemoteConfig` in the `<script>` build): four calls: `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)`**: conditions on a custom criteria match this device's value. Kept across visits; works before `Apptics.init()`.
+- **`fetchValue(name)`** and **`fetchValues({ name: default })`**: 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).