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

package/README.md

@@ -1,25 +1,761 @@
-# @zoho_apptics/apptics-js-sdk
+# Apptics JavaScript SDK
 
-JavaScript SDK for Zoho Apptics Analytics
+JavaScript/TypeScript library for [Zoho Apptics](https://www.zoho.com/apptics/) on the web: usage analytics, error tracking, API tracking, remote config, remote logging, in-app feedback and heatmaps.
 
-## Installation
+### Prerequisites
+
+- A browser app: Chrome 80+, Edge 80+, Firefox 74+ or Safari 14+.
+- A Browser app registered in the Apptics web console (Quick start → Browser), which gives you its `serviceUrl`, `zak` and `identifier`.
+
+The SDK is plain TypeScript with no framework dependency. It works with any bundler (Vite, webpack, Next.js, …) and from a `<script>` tag.
+
+## Install Apptics
 
 ```bash
-npm install @zoho_apptics/apptics-js-sdk
+npm install @zoho_apptics/apptics-js-sdk@2.0.0-beta
+```
+
+A plain `npm install @zoho_apptics/apptics-js-sdk` still installs 1.0.2, the current `latest`. Upgrading from 1.0.2? `Apptics.init()` takes different config now; see [Upgrading from 1.0.2](#upgrading-from-102).
+
+## Initialize Apptics
+
+Start Apptics once, as early as your app runs, with the values from the Apptics web console.
+
+### With a bundler
+
+```ts
+import { Apptics, AppticsEvents } from '@zoho_apptics/apptics-js-sdk';
+
+// Your web app's Apptics configuration, from the Apptics web console
+const appticsConfig = {
+  serviceUrl: 'YOUR_SERVICE_URL',
+  zak: 'YOUR_TOKEN',
+  identifier: 'YOUR_IDENTIFIER',
+  appversion: 'YOUR_APPVERSION',   // your app's version
+};
+
+// Initialize Apptics. Screens are tracked from the URL from here on, route changes included
+Apptics.init(appticsConfig);
+
+AppticsEvents.addEvent('signup', 'onboarding', { plan: 'pro' });
+```
+
+The config object is **required**, with `serviceUrl`, `zak`, `identifier` and `appversion`: `Apptics.init()` won't start without them, and logs a warning naming whatever is missing.
+
+`Apptics.init()` returns right away. The SDK finishes starting once its storage has loaded, usually within a few milliseconds. Calls you make before that are queued and run in order, so you don't have to wait. If you need to know when it's running, use `await apptics.ready()`.
+
+The SDK's objects carry the Android SDK's names — `Apptics`, `AppticsEvents`, `AppticsScreenTracker`, `AppticsApiTracker`, `AppticsLogger`, `AppticsRemoteConfig` — so code reads the same on every platform. CommonJS works too (`const { Apptics } = require('@zoho_apptics/apptics-js-sdk')`). Importing the SDK is safe during server-side rendering: nothing runs until `Apptics.init()` is called in the browser.
+
+### With a `<script>` tag (CDN)
+
+Load the browser build and call `Apptics.init()` after it. One `<script>` tag is all it takes: the build
+loads its own stylesheet (`style.css`, from the same CDN folder) for the feedback form.
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@zoho_apptics/apptics-js-sdk@2.0.0-beta/dist/apptics.min.js"></script>
+<script>
+  Apptics.init({
+    serviceUrl: 'YOUR_SERVICE_URL',
+    zak: 'YOUR_TOKEN',
+    identifier: 'YOUR_IDENTIFIER',
+    appversion: 'YOUR_APPVERSION',   // your app's version
+  });
+  // screens are tracked from the URL automatically; events are yours to send
+  AppticsEvents.addEvent('signup', 'onboarding', { plan: 'pro' });
+</script>
+```
+
+The build defines the same names as globals — `Apptics`, `AppticsEvents`, `AppticsScreenTracker`, `AppticsApiTracker`, `AppticsLogger`, `AppticsRemoteConfig`, `AppticsTrackError`, `AppticsSetUser` — so a page's code reads as it would after an import. Everything, every module included (feedback, heatmaps, remote config), is also on `window.apptics`, including `apptics.DefinedEvents` and `apptics.ApiTrackingBuilder`, which have no global of their own. Define `window.appticsReady = () => { … }` to run code once it's ready.
+
+`Apptics.init()` runs exactly once; a second call logs a warning and returns `false`. Calls that track
+or send something are ignored until `Apptics.init()` has run, and the first such call logs a console
+warning saying so.
+
+**Pin the version** (`@2.0.0-beta`) rather than a tag or range such as `@beta`, so a release can't change what your pages load. See [Loading from a CDN](#loading-from-a-cdn) for module builds, unpkg and subresource integrity.
+
+### Frameworks
+
+React, Vue, Angular, Svelte, Ember, Solid, jQuery and hand-written JS all start the same way, and every one of them needs only that: the SDK follows the route itself ([automatic screen tracking](#automatic-screen-tracking)). To name screens from your router instead, call `AppticsScreenTracker.inScreen()` from the hook in the last column: a call made as the route changes replaces the automatic view, and `track_screen: false` turns the automatic one off altogether, which is what the recipes in `examples/frameworks` do.
+
+| Framework | Start | Screen on navigation, with `track_screen: false` |
+|---|---|---|
+| React, Remix, Gatsby | `useEffect(() => { Apptics.init(config); }, [])` | `useLocation()` in an effect |
+| Vue 3 | a plugin: `app.use(apptics, { router })` | `router.afterEach(to => AppticsScreenTracker.inScreen(to.path))` |
+| Angular | an injectable service | `router.events` filtered to `NavigationEnd` |
+| Svelte, SvelteKit | `src/hooks.client.ts`, or `onMount` | `afterNavigate` |
+| Ember | an instance initializer | `router.on('routeDidChange', …)` |
+| Next.js | `'use client'` component in the layout | `usePathname()` in an effect |
+| Nuxt 3 | `plugins/apptics.client.ts` | `useRouter().afterEach(…)` |
+| Plain JS, jQuery | the `<script>` tag itself | `AppticsScreenTracker.inScreen()` where you change view |
+
+**Server-side rendering** (Next, Nuxt, SvelteKit, Remix, Angular Universal): importing the SDK on the server is safe — `Apptics.init()` returns `false` instead of throwing — but it tracks nothing there. Start it from a browser-only hook, as the recipes do. There is no Node/server-side tracking: `engines.node` in `package.json` is the floor for building the package and running its CLI.
+
+## Error Tracking
+
+Uncaught errors and unhandled promise rejections are tracked automatically, as JS errors in the console.
+
+Report an error your code caught:
+
+```ts
+import { AppticsTrackError } from '@zoho_apptics/apptics-js-sdk';
+
+try {
+  doSomething();
+} catch (error) {
+  AppticsTrackError({ type: 'error', error });
+}
+```
+
+`AppticsTrackError` also accepts `error` and `unhandledrejection` events as they are. Turn the automatic tracking off with `enableGlobalErrorHandler(false)`.
+
+React, Vue, Angular, SvelteKit and Ember catch render errors themselves, so those never reach `window.onerror`. Report them from the framework's own error hook:
+
+| Framework | Error hook |
+|---|---|
+| React | an error boundary: `componentDidCatch(error) { AppticsTrackError({ type: 'error', error }); }` |
+| Vue 3, Nuxt 3 | `app.config.errorHandler = (error) => AppticsTrackError({ type: 'error', error })` (Nuxt: `nuxtApp.hook('vue:error', …)`) |
+| Angular | an `ErrorHandler` whose `handleError(error)` calls `AppticsTrackError({ type: 'error', error })`, provided as `{ provide: ErrorHandler, useClass: … }` |
+| SvelteKit | `handleError({ error })` in `src/hooks.client.ts` |
+| Ember | `Ember.onerror = (error) => AppticsTrackError({ type: 'error', error })` |
+
+## Event Tracking
+
+Track an event, with an optional group and properties:
+
+```ts
+import { AppticsEvents } from '@zoho_apptics/apptics-js-sdk';
+
+AppticsEvents.addEvent('eventName', 'eventGroupName', { propKey: 'propValue' });
+```
+
+Event and group names start with a letter, followed by letters, digits or `_`, at most 100
+characters, and may not start with `ap_` or `AP_`, which is reserved for defined events. As on
+Android, an event with an invalid name or group is not logged, and the console says why. A group
+left out is `default`.
+
+### Defined events
+
+Apptics' ready-made events, as Android's `DefinedEvents`, each with its own `AP_` group. They are
+not tracked automatically; log the ones that apply:
+
+```ts
+import { AppticsEvents, DefinedEvents } from '@zoho_apptics/apptics-js-sdk';
+
+AppticsEvents.addEvent(DefinedEvents.AP_USER_LOGIN);
+AppticsEvents.addEvent(DefinedEvents.AP_SEARCH, { results: 12 });
+```
+
+| Group | Events |
+|---|---|
+| `AP_APP_LIFE_CYCLE` | `AP_APP_INSTALL`, `AP_APP_UNINSTALL`, `AP_APP_UPDATE`, `AP_APP_CRACKED`, `AP_APP_OPEN`, `AP_APP_CLEAR_DATA`, `AP_APP_FOREGROUND`, `AP_APP_BACKGROUND`, `AP_APP_OUT_OF_MEMORY`, `AP_APP_FIRST_OPEN`, `AP_APP_LAUNCHING`, `AP_APP_RESIGN_ACTIVE`, `AP_APP_WILL_CONNECT` |
+| `AP_USER_LIFE_CYCLE` | `AP_USER_SIGNUP`, `AP_USER_LOGIN`, `AP_USER_LOGOUT` |
+| `AP_APPLICATION` | `AP_DEEP_LINK_OPEN`, `AP_DEEP_LINK_UPDATE`, `AP_DEEP_LINK_FIRST_OPEN`, `AP_IN_APP_PURCHASE`, `AP_NOTIFICATION_RECEIVE`, `AP_NOTIFICATION_OPEN`, `AP_NOTIFICATION_DISMISS`, `AP_NOTIFICATION_FOREGROUND`, `AP_SEARCH`, `AP_BATTERY_LOW`, `AP_BATTERY_FULL`, `AP_LOW_POWER_MODE_ON`, `AP_LOW_POWER_MODE_OFF` |
+| `AP_OTHERS` | `AP_NETWORK_REACHABILITY_CHANGE`, `AP_NETWORK_BANDWIDTH_CHANGE`, `AP_SWITCH_THEME_LIGHT`, `AP_SWITCH_THEME_DARK`, `AP_SWITCH_THEME_CUSTOM`, `AP_SWITCH_ORIENTATION_LANDSCAPE`, `AP_SWITCH_ORIENTATION_PORTRAIT` |
+| `AP_OS` | `AP_OS_UPDATE`, `AP_OS_UNSUPPORTED` |
+
+With a `<script>` tag it is `apptics.DefinedEvents`.
+
+Clicks can also be tracked from markup, without code:
+
+```html
+<section apgroupaction="checkout">
+  <button apeventaction="buy_clicked" apeventprops='{"plan":"pro"}'>Buy</button>
+</section>
+```
+
+Clicking the button, or anything inside it, tracks `buy_clicked` in group `checkout`.
+
+Properties: keys start with a letter, followed by up to 49 letters, digits or `_`, and may not
+start with `ap_`. Values are numbers, booleans or strings of up to 250 characters; anything else
+(an object, an array) is sent as its JSON text. As on Android, a property that breaks these rules
+is dropped and the event is still logged with the rest. At most 24 properties and 7,666
+characters in all; past that the later ones are dropped. The same rules apply to screen and error
+properties.
+
+## Screen Tracking
+
+Screens are tracked automatically, from the URL (see [below](#automatic-screen-tracking)). To
+record one yourself — with your own name, or with properties — call `AppticsScreenTracker.inScreen`, as on Android:
+
+```ts
+import { AppticsScreenTracker } from '@zoho_apptics/apptics-js-sdk';
+
+AppticsScreenTracker.inScreen('checkout');
+```
+
+Each screen view records how long it lasted. It ends when the next screen starts, when the page
+is hidden (coming back starts a new view of the same screen), or when its session ends.
+`AppticsScreenTracker.inScreen` returns the view's id; hand it to `AppticsScreenTracker.outScreen` to end the view yourself — a dialog
+that closes without the page changing, say — as Android's `AppticsScreenTracker.outScreen` does:
+
+```ts
+import { AppticsScreenTracker } from '@zoho_apptics/apptics-js-sdk';
+
+const id = AppticsScreenTracker.inScreen('settings');   // when the screen is shown
+AppticsScreenTracker.outScreen(id);                        // when it is dismissed
+```
+
+`AppticsScreenTracker.inScreen` returns `''` for a name that isn't a valid screen name.
+
+Screen names: up to 99 characters of letters, digits, spaces and `. - _ & / :`. Events, errors,
+feedback and heatmap records are attributed to the current screen: the one `AppticsScreenTracker.inScreen()` last
+named, or else the one automatic tracking named from the URL. A heatmap record always has a
+screen view behind it: with automatic tracking off and no `AppticsScreenTracker.inScreen()` call, the first record
+on a page records a view of the page, named the same way from its path, and a new one when the
+path changes.
+
+An `AppticsScreenTracker.inScreen()` call made during a navigation — from a router hook, say —
+replaces the automatic view of it, so the navigation counts once, under your name. The automatic view waits
+300 ms for such a call before it is recorded; a call after that is a screen view of its own.
+
+### Automatic screen tracking
+
+On by default: the SDK records screen views from the URL, with no `AppticsScreenTracker.inScreen()` calls. It records the page the SDK starts on, then every navigation: `history.pushState` / `replaceState`
+(React Router, Vue Router, Angular, Next.js and other single-page routers), back and forward, and
+`#/` hash routes. The screen is named by its path, without the query string, so `/search?q=shoes`
+is `/search` and `/#/orders` is `/orders`. Characters a screen name can't hold become `_`, and a
+name stops at 99 characters. A plain `#anchor` and a navigation that lands on the same path are
+not new views.
+
+Paths with ids in them make every record its own screen. To give a route your own name —
+`/orders/123` and `/orders/456` as one `Order detail` — call `AppticsScreenTracker.inScreen()` from your router as
+the route changes: that replaces the automatic view of the navigation.
+
+**An app that names its screens from its router** keeps doing so with `AppticsScreenTracker.inScreen()`: a call
+within 300 ms of the navigation replaces the automatic view (see
+[Screen Tracking](#screen-tracking)). To track only the screens you name yourself — screens that
+aren't routes, or hooks that run later than that — turn automatic tracking off:
+
+```ts
+Apptics.init({ ...config, track_screen: false });
+```
+
+`reset()` takes the history wrappers off; the `Apptics.init()` it runs puts them back.
+
+## Track User
+
+Register the signed-in user:
+
+```ts
+import { AppticsSetUser } from '@zoho_apptics/apptics-js-sdk';
+
+AppticsSetUser('user-id', 'customer-group-id');   // the group is optional
+```
+
+`AppticsSetUser` switches tracking to "with PII" (see [Tracking settings](#tracking-settings)). `getUser()` returns the active user.
+
+### Track User with properties
+
+```ts
+import { AppticsSetUser, users } from '@zoho_apptics/apptics-js-sdk';
+
+const properties = new users.UserBuilder()
+  .setFirstName('Ana')
+  .setEmailAddress('ana@zylker.com')
+  .setPlanType('pro')
+  .setCustomProperties({ team: 'design' })
+  .build();
+
+AppticsSetUser('user-id', 'customer-group-id', properties);
+```
+
+The builder also has `setLastName`, `setCompanyName`, `setContactNumber`, `setCountry`, `setRegion`, `setCity`, `setGeoLocation`, `setGender`, `setTimezone`, `setLanguage`, `setEngagementScore` and `setDateOfBirth`. `build()` validates the properties against what the server accepts.
+
+## Tracking settings
+
+Set what the SDK may track for this visitor:
+
+```ts
+import { setTrackingStatus, AP_TRACKING_STATUS } from '@zoho_apptics/apptics-js-sdk';
+
+setTrackingStatus(AP_TRACKING_STATUS.USAGE_TRACKING_WITHOUT_PII);
 ```
 
-#### intialization 
+| Status | Value | Meaning |
+|---|---|---|
+| `USAGE_TRACKING_WITH_PII` | 1 | Track, with the user's identity |
+| `USAGE_TRACKING_WITHOUT_PII` | 4 | Track anonymously (the default) |
+| `NO_TRACKING` | -1 | Track nothing |
+
+`getTrackingStatus()` returns the current one.
 
-1. Register your app and copy `apptics snippet` from Apptics web console.
-2. Once you have created the Project and added your app, copy the apptics snippet, and move the file into the project index file.
+### Privacy
 
+- The browser's Do Not Track setting is honoured unless `ignore_do_not_track: true` is passed to `Apptics.init()`.
+- Nothing is tracked for known crawlers.
+- Heatmaps name an element from an attribute the author chose (`data-ap-label`, `aria-label`, `name`, `id`, `title`); its visible text is used only with `USAGE_TRACKING_WITH_PII`.
 
-## Usage
+## API Tracking
 
-```javascript
-const Apptics = require('@zoho_apptics/apptics-js-sdk');
+Record the API calls your app makes, for the console's API page. Either let the SDK wrap
+`fetch` and `XMLHttpRequest`:
+
+```ts
+Apptics.init({ ...config, track_api: true });   // record every fetch and XHR call
 ```
 
+`enableApiTracking(on)` switches it later. Which hosts and endpoints are recorded is set with
+[`AppticsApiTracker.configure`](#configuring-api-tracking).
+
+or record calls yourself with `AppticsApiTracker.startTrackApi` / `endTrackApi`, as on Android — the
+SDK times the call between the two:
+
+```ts
+import { AppticsApiTracker } from '@zoho_apptics/apptics-js-sdk';
+
+const id = AppticsApiTracker.startTrackApi('https://api.example.com/orders/42', 'GET');
+const response = await fetch('https://api.example.com/orders/42');
+AppticsApiTracker.endTrackApi(id, response.status, response.statusText);
+```
+
+Between them, automatic tracking and `AppticsApiTracker.startTrackApi` / `endTrackApi` are the
+two ways a call is recorded.
+
+### Configuring API tracking
+
+Build the rules with `ApiTrackingBuilder` — as `UserBuilder` builds user properties, and with
+the names of Android's `AppticsApiTracker.configure` — and apply them once, before the requests
+they should cover. It works before `Apptics.init()`:
+
+```ts
+import { ApiTrackingBuilder, AppticsApiTracker } from '@zoho_apptics/apptics-js-sdk';
+
+AppticsApiTracker.configure(new ApiTrackingBuilder()
+  .allowOnlyDomains('api.yourapp.com', 'api.yourapp.in', 'api.yourapp.ae')
+  .groupDomains('api.yourapp.*')
+  .ignoreEndpoint('/health', '/ping', '/internal/**')
+  .addPattern('/v2/catalog/{categoryId}/items/{itemId}')
+  .preserveSegments('v1', 'v2')
+  .build());
+```
+
+The rules apply to every call, the ones `track_api` catches and the ones you report yourself.
+
+**Path normalization**, on by default, so calls group by endpoint rather than by id:
+
+| Called | Recorded as |
+|---|---|
+| `GET /users/42/orders` | `/users/*/orders` (numeric id) |
+| `GET /users/0b9e1f2a-…-0c1d2e3f4a5b/profile` | `/users/*/profile` (UUID) |
+| `DELETE /sessions/eyJhbGciOi….….` | `/sessions/*` (JWT) |
+| `GET /products/search?q=shoes` | `/products/search` (the query string is always removed) |
+
+| Builder call | Effect |
+|---|---|
+| `ignoreDomains(...)` / `allowOnlyDomains(...)` | Never record these hosts / record only these |
+| `allowOnlyTLDs('.com', ...)` / `ignoreTLDs('.local', ...)` | Record only / never hosts ending in these |
+| `ignoreDomainPrefixes('dev.', ...)` / `ignoreDomainSuffixes('.cdn.net', ...)` | Never record hosts starting or ending with these |
+| `groupDomains('api.myapp.*', ...)` | Record `api.myapp.com`, `.in`, `.eu`… as one host, `api.myapp.*` |
+| `ignoreEndpoint('/health', '/internal/*', '/users/{id}/x', '/debug/**')` | Never record these paths: exact, `*` or `{name}` for one segment, `**` at the end for everything under it |
+| `addPattern('/v1/accounts/{accountId}')` | Record a matching path as the pattern, each `{name}` as `*`. Tried before auto-detection |
+| `preserveSegments('v1', '404', ...)` | Never turn these segments into `*` |
+| `autoDetection(false)` | Normalize only `addPattern` matches; record every other path as it is |
+
+An ignore rule always wins over an allow list. A second `AppticsApiTracker.configure()` replaces the
+first.
+
+The SDK's own requests are never recorded, and neither are calls to `localhost` or a bare IP
+address: the server only accepts hostnames with a dot and a letters-only suffix, so the SDK drops
+those calls and says so in the console. `enableApiTracking(false)` removes the wrappers again.
+With a `<script>` tag, `AppticsApiTracker` is a global as it is here, alongside
+`apptics.enableApiTracking()` and `new apptics.ApiTrackingBuilder()`.
+
+## Remote Config
+
+Read parameters set in the console. Its own entry point, so apps that don't use it don't ship it:
+
+```ts
+import { AppticsRemoteConfig } from '@zoho_apptics/apptics-js-sdk/remote-config';
+
+// one value, or several with their defaults, as on Android
+const banner = await AppticsRemoteConfig.fetchValue('bannerText');            // null if there is none
+const values = await AppticsRemoteConfig.fetchValues({ primaryColor: '#0b6e4f', maxItems: '10' });
+
+// what this device is for a custom criteria the console defines
+AppticsRemoteConfig.setCustomConditionValue('plan_tier', 'gold');
+```
+
+Values are text, as the console stores them: `Number(values.maxItems)`,
+`values.showBanner === 'true'` or `JSON.parse(...)` turn them into what the app needs.
+
+The SDK fetches once on its own when it starts (or when this module is imported after it has),
+so values are this session's without a call of yours.
+
+**Fetching.** `fetchValue` and `fetchValues` reuse a fetch from the last five minutes
+rather than asking the server again, so reading a value on every render costs no requests. Pass
+`coldFetch` (`true` as the last argument) to ask the server regardless; that is limited to three
+calls a minute, and a call past it is answered as a failed fetch. Each also takes a callback,
+as on Android, and returns a Promise either way.
+
+**When a fetch fails** (offline, or a server error), they answer with the values fetched before.
+`AppticsRemoteConfig.setFallbackWithOfflineValue(false)` makes them answer with `null` — or the defaults
+you passed to `fetchValues` — instead.
+
+**Custom conditions.** A console condition can be on a custom criteria — a key with a list of
+values. `setCustomConditionValue(key, value)` says what this device is for that key, and the
+condition matches when the value is one of the listed ones. Values are kept across visits and
+applied at once, without a fetch; an empty value removes one, and `reset()` clears them. It works
+before `Apptics.init()`.
+
+Conditions on the user — the customer group, for one — are re-applied on their own once
+`AppticsSetUser` has registered the user, so the next read answers for them.
+
+| Call | Notes |
+|---|---|
+| `fetchValue(name, callback?, coldFetch?)` | One parameter for this session; `null` when the console has none. |
+| `fetchValues({ name: default }, callback?, coldFetch?)` | Several at once; each name gets its default when it has no value. |
+| `setFallbackWithOfflineValue(on)` | Whether a failed fetch answers with the values fetched before (default) or with `null` and defaults. |
+| `setCustomConditionValue(key, value)` | What this device is for a custom criteria; an empty value removes it. |
+
+With a `<script>` tag, `AppticsRemoteConfig` is a global as it is here.
+
+## Remote Logger
+
+Send your app's log lines to the console's Remote Logger page with `AppticsLogger`, as on
+Android: five levels, each taking a tag and a message. The logger is disabled by default; enable
+it first:
+
+```ts
+import { AppticsLogger } from '@zoho_apptics/apptics-js-sdk';
+
+AppticsLogger.enable();
+
+AppticsLogger.v('Boot', 'Verbose');
+AppticsLogger.d('Boot', 'Debug');
+AppticsLogger.i('Checkout', 'Payment started');
+AppticsLogger.w('Checkout', 'Retrying the payment');
+AppticsLogger.e('Checkout', 'Payment failed', { orderId: 42 }, err);
+
+AppticsLogger.disable();   // stops it again
+```
+
+| Call | Level on the Remote Logger page |
+|---|---|
+| `AppticsLogger.v(tag, message, ...details)` | 1, Verbose |
+| `AppticsLogger.d(tag, message, ...details)` | 2, Debug |
+| `AppticsLogger.i(tag, message, ...details)` | 3, Info |
+| `AppticsLogger.w(tag, message, ...details)` | 4, Warning |
+| `AppticsLogger.e(tag, message, ...details)` | 5, Error |
+| `AppticsLogger.enable()` / `AppticsLogger.disable()` / `AppticsLogger.isEnabled()` | Start, stop, and check the logger |
+
+The tag leads the message as `[tag] message`; an empty tag adds nothing. Details are appended to the message: an `Error`
+as its stack, anything else as JSON. Each line records the time it was logged and the function,
+file and line that logged it, even when logged before start-up finishes. Lines are stored before
+they are sent and go out in batches of up to 50: a line survives a failed send and a reload, and
+is removed once the server accepts it. At most 1 MB of lines waits at once, oldest dropped first,
+as on Android, and a line is trimmed to 10,000 characters. Nothing is recorded while the server
+has the remote logger switched off, or while tracking is off. `AppticsLogger.disable()` stops it.
+
+Unlike Android, which uploads at the next cold start or on a schedule, lines go out about a
+second after they're logged: a browser tab can close at any moment, and waiting would lose them.
+
+To see the lines in the browser console as well while you develop — Android's `showLogs` —
+pass `show_logs: true` to `Apptics.init()`. It prints each line at its level (`console.debug`, `info`,
+`warn`, `error`), with objects left expandable, whether or not the remote logger is enabled.
+`console_log` is a different switch: it logs the SDK's own activity, not your lines.
+
+### SDK diagnostics
+
+The SDK also reports its own failures to the same page — an event refused for a bad name, a batch
+that never left, a session that couldn't open — tagged with the module it happened in (`Session`,
+`Screen`, `Event`, `API`, `Properties`). It answers "this app reports no data, what is the SDK
+doing out there?" and carries no app data. It is off by default and separate from `AppticsLogger`:
+
+```ts
+Apptics.init({ ...config, remote_log: true });   // turn the SDK's own reports on
+```
+
+## In-App Feedback
+
+The feedback form is its own entry point, so apps that don't use it don't download it. With a
+`<script>` tag it is already on `window.apptics`.
+
+### Show feedback screen
+
+```ts
+import { feedbackOpen, feedbackClose } from '@zoho_apptics/apptics-js-sdk/feedback';
+import '@zoho_apptics/apptics-js-sdk/style.css';
+
+feedbackOpen();     // show the form
+feedbackClose();    // close it from your own code, when needed
+```
+
+With a bundler, import `style.css` as above. The CDN builds (`apptics.min.js` and
+`feedback.esm.min.js`) load it themselves.
+
+The form offers Bug, Feedback, Help and Report, with up to 5 attachments (10 MB total). It offers
+screen recording when the page also loads Zoho Quartz and `Apptics.init()` was given `DC`,
+`quartz_workspace_key` and `quartz_department_key` (see [Configuration](#configuration)).
+Otherwise — or with any of them set to `-` — the recording checkbox and its label are not shown.
+
+### Send Feedback/Bug Report programmatically
+
+```ts
+import { sendFeedback } from '@zoho_apptics/apptics-js-sdk/feedback';
+import { AP_FEEDBACK_TYPE } from '@zoho_apptics/apptics-js-sdk';
+
+try {
+  await sendFeedback(AP_FEEDBACK_TYPE.BUG, 'Checkout is broken');
+  // sent
+} catch (err) {
+  // not sent: the SDK hasn't started (no Apptics.init()), the browser is offline, or the server refused it
+}
+```
+
+`sendFeedback(type?, message?, attachments?, logFiles?, includeDyninfo?, includeLog?)` returns a
+Promise that resolves once the feedback is sent and rejects when it wasn't. `type` is
+`AP_FEEDBACK_TYPE.BUG` (0), `FEEDBACK` (1), `HELP` (2) or `REPORT` (3).
+
+### Attach logs and diagnostics with Feedback
+
+```ts
+import { addFeedbackLog, addDiagnosticsInfo } from '@zoho_apptics/apptics-js-sdk';
+
+addFeedbackLog('token refresh failed, retrying');       // one timestamped line
+addDiagnosticsInfo('Auth', 'scheme', 'oauth');          // grouped key/value
+addDiagnosticsInfo('Auth', 'expiry', 3600);
+```
+
+Both are on the main entry point, so recording context costs nothing in bundle size for apps that
+never open the form. Nothing is sent as it happens: entries wait in storage until feedback is sent,
+and then travel with it as two text files.
+
+| File | Holds | Sent when |
+|---|---|---|
+| `feedbacklog.txt` | `addFeedbackLog` lines, in order, each prefixed with its ISO timestamp | There are lines, unless `includeLog` is `false` |
+| `dyninfo.txt` | `addDiagnosticsInfo` entries as `[heading]` blocks, then a `[Device Info]` block | There are diagnostics, or `includeDyninfo` is `true` |
+
+Only the entries a submission actually carried are removed once the server has them, so anything
+recorded while a submission is in flight waits for the next one. Entries older than
+`batch_request_timeout` days are left out, at most 1,000 are kept (oldest dropped first), a single
+message is truncated at 10,000 characters, and neither file is sent above 2 MB.
+
+## Heatmaps
+
+Records where people click and how far they scroll, for the console's heatmaps. Its own entry
+point, so an app that doesn't import it ships none of the capture code.
+
+```ts
+import { Apptics } from '@zoho_apptics/apptics-js-sdk';
+import { enableHeatmap } from '@zoho_apptics/apptics-js-sdk/heatmap';
+
+Apptics.init({ ...config, track_heatmap: true });
+// or turn it on later: enableHeatmap(true)
+```
+
+Importing the module is what makes `track_heatmap` do anything — the flag on its own has nothing
+to switch on. With a `<script>` tag it's already there as `apptics.enableHeatmap()`.
+
+| Call | Notes |
+|---|---|
+| `enableHeatmap(on?)` | Starts or stops capture. |
+
+Heatmap records go out with the rest of the stored data: on the flush timer, or when you call
+`flush()`.
+
+A click gives coordinates, normalized position, a label for the element, and whether it was
+clickable, repeated in frustration (`is_rage_click`) or changed nothing (`is_dead_click`).
+Scrolling is coalesced into one record per gesture — direction, duration, velocity and how far
+down the page it left you. At most `heatmap_max_per_session` records per visit (default 500),
+then capture pauses.
+
+## Debugging
+
+Two tools, both off by default: debug mode, which you follow in the Apptics web console, and
+console logs in the browser.
+
+### Debug mode
+
+When a payload isn't showing up in the console, turn on debug mode. It sends engagement,
+exception and log payloads to their `debug/` endpoints, which keep a traceable record of each
+request on the server: follow them in the Apptics web console, along with the request id and the
+link to the server's logs for that request.
+
+```ts
+Apptics.init({ ...config, debug: true });   // start in debug mode
+
+// or turn it on and off at any time
+import { enableDebug, disableDebug } from '@zoho_apptics/apptics-js-sdk';
+
+enableDebug();    // turn debug mode on
+disableDebug();   // and off again
+```
+
+`enableDebug()` and `disableDebug()` don't need `Apptics.init()`: call it before `Apptics.init()`, while the SDK starts or at any
+time after, and it takes effect at once. What the app chooses this way holds for the rest of the
+page's life, over `debug` in `Apptics.init()` and through `reset()`, so a page whose config turns
+debug mode on can still switch it off with `disableDebug()`. With a `<script>` tag they are
+`apptics.enableDebug()` and `apptics.disableDebug()`.
+
+Debug mode changes where payloads go, not what is in them. It switches itself off after an hour
+with nothing tracked, so a forgotten tab stops tracing on its own.
+
+| Key / call | Default | Notes |
+|---|---|---|
+| `debug` | `false` | Start in debug mode, unless the app has already called `enableDebug()` or `disableDebug()`. |
+| `enableDebug()` / `disableDebug()` | | Turn debug mode on or off, with or without `Apptics.init()`. |
+| `device_name` | unset | Names this device in the debug stream, so testers on the same build can tell their requests apart. Without it, while debug mode is on, a name is made from the browser and OS. |
+
+### Console logs
+
+Log the SDK's activity — what it tracks, stores and sends, and the trace of each debug-mode
+request — to the browser console:
+
+```ts
+Apptics.init({ ...config, console_log: true });
+```
+
+## Configuration
+
+Everything `Apptics.init(config)` accepts.
+
+| Key | Required | Description |
+|---|---|---|
+| `serviceUrl` | yes | The Apptics host every request goes to, from the Apptics web console (a trailing slash is ignored) |
+| `zak` | yes | The app's token, from the Apptics web console |
+| `identifier` | yes | The app identifier registered in the Apptics web console |
+| `appversion` | yes | Your app's version, e.g. `2.4.0`. No default: everything the SDK reports is tied to the build it came from. Changing it registers the new version |
+| `debug` | | Debug mode: follow requests in the Apptics web console (see [Debugging](#debugging)) |
+| `console_log` | | Log the SDK's activity to the browser console |
+| `ignore_do_not_track` | | Track even when the browser sends Do Not Track |
+| `remote_log` | | `true` makes the SDK report its own failures (see [SDK diagnostics](#sdk-diagnostics)). Off by default |
+| `track_session` | | `false` records no sessions, while events, screens and the rest still are — Android's `automaticSessionsTrackingStatus = false`. On by default |
+| `show_logs` | | Also print the app's `AppticsLogger` lines to the browser console, like Android's `showLogs` (see [Remote Logger](#remote-logger)) |
+| `track_api` | | Record the app's own fetch and XHR calls. Off by default; which hosts and endpoints, through `AppticsApiTracker.configure` (see [API Tracking](#api-tracking)) |
+| `track_heatmap`, `heatmap_max_per_session` | | Record clicks and scrolls (see [Heatmaps](#heatmaps)) |
+| `track_screen` | | Record a screen view for every navigation, named by its path. On by default; `false` turns it off (see [Automatic screen tracking](#automatic-screen-tracking)) |
+| `device_name` | | Names this device in debug mode (see [Debugging](#debugging)) |
+| `DC`, `quartz_workspace_key`, `quartz_department_key` | | Enable Quartz screen recording in the feedback form (`DC`: US, EU, IN, AU, CN, CA, JP, SA, AE; `-` disables). The recording checkbox is shown only when all three are set and the page has loaded Quartz |
+
+The older snippet names are still accepted: `base_domain` for `serviceUrl` and `token` for `zak`.
+`aaid`, `zsoid` and `projectID` are no longer needed, and are ignored if passed.
+
+### Timing
+
+Data is stored first and sent on a timer, so these control how often the SDK talks to the server. All are optional; a value outside its range is ignored with a warning and the default is used.
+
+| Key | Default | Range | Description |
+|---|---|---|---|
+| `batch_flush_interval` | `30000` | 1000 – 3600000 | How often stored data is sent, in milliseconds |
+| `getupdates_interval` | `120000` | 10000 – 86400000 | How often the server's tracking settings are checked, in milliseconds; the server can ask for a longer wait |
+| `batch_size` | `50` | 1 – 500 | Most items in one request (also capped at 1 MB) |
+| `batch_request_timeout` | `7` | 1 – 30 | Days an unsent item is kept before it is dropped |
+| `inactiveduration` | `30` | 1 – 1440 | Idle minutes that end a session |
+| `min_session_duration` | `5000` | 0 – 60000 | Milliseconds a visit must last before its session is recorded; anything tracked sooner records it at once. `0` turns the wait off |
+
+Data is also sent when you call `flush()`, when the page is hidden, when the tab closes, and when the browser comes back online — the interval is the floor, not the only trigger.
+
+## API reference
+
+| Call | Notes |
+|---|---|
+| `Apptics.init(config)` | Starts the SDK. Returns `true` when start-up has begun. |
+| `ready()` | Promise that resolves `true` once the SDK is running (`false` if it can't start). |
+| `AppticsEvents.addEvent(name, group?, props?)` / `AppticsEvents.addEvent(DefinedEvents.X, props?)` / `DefinedEvents` | See [Event Tracking](#event-tracking). |
+| `AppticsScreenTracker.inScreen(name, props?)` → id / `AppticsScreenTracker.outScreen(id)` | See [Screen Tracking](#screen-tracking). |
+| `AppticsTrackError(event, props?)` / `enableGlobalErrorHandler(on)` | See [Error Tracking](#error-tracking). |
+| `AppticsSetUser(userid, groupid?, props?)` / `getUser()` / `users.UserBuilder` | See [Track User](#track-user). |
+| `setTrackingStatus(status)` / `getTrackingStatus()` | See [Tracking settings](#tracking-settings). |
+| `AppticsApiTracker.startTrackApi(url, method?)` / `endTrackApi(id, code, message?)` / `configure(rules)` / `ApiTrackingBuilder` / `enableApiTracking(on?)` | See [API Tracking](#api-tracking). |
+| `AppticsLogger.enable()` / `disable()` / `isEnabled()` / `v / d / i / w / e(tag, message, …)` | See [Remote Logger](#remote-logger). |
+| `AppticsRemoteConfig.fetchValue` / `fetchValues` / `setCustomConditionValue` / `setFallbackWithOfflineValue` | From `/remote-config`; see [Remote Config](#remote-config). |
+| `addFeedbackLog(message)` / `addDiagnosticsInfo(heading, key, value?)` | See [Attach logs and diagnostics](#attach-logs-and-diagnostics-with-feedback). |
+| `flush()` | Send stored data now (engagement, errors and heatmap records); it's otherwise sent every 30 s (see [Timing](#timing)). |
+| `enableDebug()` / `disableDebug()` | See [Debugging](#debugging). |
+| `reset()` | Clear stored identity, queued data and remote config values, then start again. |
+
+Entry points: `@zoho_apptics/apptics-js-sdk` (everything above), `/feedback`, `/remote-config`
+(see [Remote Config](#remote-config)), `/heatmap` and `/style.css`. Types ship with the package:
+`import type { AppticsConfig, TrackingStatus } from '@zoho_apptics/apptics-js-sdk'`.
+
+## Loading from a CDN
+
+For `<script type="module">`, load the minified ESM build (a few requests instead of one per module) and call `Apptics.init()` yourself:
+
+```html
+<script type="module">
+  import { Apptics, AppticsEvents } from 'https://cdn.jsdelivr.net/npm/@zoho_apptics/apptics-js-sdk@2.0.0-beta/dist/apptics.esm.min.js';
+  // The feedback form is a separate file, so pages without it don't download it
+  import { feedbackOpen } from 'https://cdn.jsdelivr.net/npm/@zoho_apptics/apptics-js-sdk@2.0.0-beta/dist/feedback.esm.min.js';
+
+  Apptics.init({
+    serviceUrl: 'YOUR_SERVICE_URL',
+    zak: 'YOUR_TOKEN',
+    identifier: 'YOUR_IDENTIFIER',
+    appversion: 'YOUR_APPVERSION',   // your app's version
+  });
+  // screens are tracked from the URL automatically
+  AppticsEvents.addEvent('signup', 'onboarding', { plan: 'pro' });
+</script>
+```
+
+| File | For | Size (gzipped) |
+|---|---|---|
+| `dist/apptics.min.js` | `<script>` pages; sets `window.apptics`, includes every module | ~39 kB |
+| `dist/apptics.esm.min.js` | `<script type="module">`; analytics only (with the `dist/chunks/` files it imports) | ~27 kB |
+| `dist/feedback.esm.min.js` | the feedback form, for module pages | ~11 kB more |
+| `dist/heatmap.esm.min.js` | heatmap capture, for module pages | ~3 kB more |
+| `dist/style.css` | the feedback form's styles; the CDN builds load it themselves | ~3 kB |
+
+The module files share one copy of the SDK through `dist/chunks/`, so load them all from the same version and path.
+
+unpkg works the same way: `https://unpkg.com/@zoho_apptics/apptics-js-sdk@2.0.0-beta/dist/apptics.min.js`. Add `defer` if you don't need the SDK before the page renders. For a subresource-integrity hash:
+
+```bash
+curl -s https://cdn.jsdelivr.net/npm/@zoho_apptics/apptics-js-sdk@2.0.0-beta/dist/apptics.min.js \
+  | openssl dgst -sha384 -binary | openssl base64 -A
+```
+
+```html
+<script src="…/apptics.min.js" integrity="sha384-…" crossorigin="anonymous"></script>
+```
+
+## Upgrading from 1.0.2
+
+### What you need to change
+
+- **The calls have the Android SDK's names.** Rename them everywhere, router hooks included: a
+  call to an old name left in place throws.
+
+  | 1.0.2 | Now |
+  |---|---|
+  | `apptics.init(config)` | `Apptics.init(config)` |
+  | `apptics.trackEvent(name, group, props)` | `AppticsEvents.addEvent(name, group, props)` |
+  | `apptics.trackScreen(name, props)` | `AppticsScreenTracker.inScreen(name, props)`, which also returns the view's id for `AppticsScreenTracker.outScreen(id)` |
+  | `apptics.trackError(event, props)` | `AppticsTrackError(event, props)` |
+  | `apptics.setUser(userid, groupid, props)` | `AppticsSetUser(userid, groupid, props)` |
+
+  The rest — `setTrackingStatus`, `getUser`, `flush`, `reset`, the feedback form — keep their names.
+
+- **`Apptics.init()` takes new config.** Pass `serviceUrl`, `zak`, `identifier` and `appversion`, all required. The SDK gets `aaid` and the portal and project ids from the server itself, so `aaid`/`aaID`, `zsoid` and `projectID` are no longer needed and are ignored if passed. Without a required key, `Apptics.init()` logs which one is missing and returns `false`.
+- **`appversion` is required.** 1.0.2 quietly defaulted it to `1.0`, which attributed every session, error and crash to a version that was never shipped. Pass your real build version.
+- **npm users can import the SDK.** 1.0.2 exported nothing, so it only worked alongside the console snippet. Now:
+
+  ```ts
+  import { Apptics } from '@zoho_apptics/apptics-js-sdk';
+  Apptics.init({ serviceUrl, zak, identifier, appversion });
+  ```
+
+- **The feedback form is its own entry point for npm users:** `import { feedbackOpen } from '@zoho_apptics/apptics-js-sdk/feedback'`, plus `import '@zoho_apptics/apptics-js-sdk/style.css'`. `addFeedbackLog()` and `addDiagnosticsInfo()` are on the main entry point. The `<script>` build still has everything on `window.apptics`.
+
+### Behaviour you may notice
+
+- **`debug: true` now turns on debug mode** (requests followed in the Apptics web console). In 1.0.2 it logged to the browser console; that is `console_log: true` now.
+- When the Apptics server tells the SDK to stop tracking an app version, it stops; 1.0.2 ignored that signal.
+- `ignore_do_not_track: true` now ignores the browser's Do Not Track setting; in 1.0.2 it disabled tracking.
+- `mute()` and `unmute()` are gone. To stop tracking, use `setTrackingStatus(AP_TRACKING_STATUS.NO_TRACKING)`; unlike `mute()`, it is stored across visits.
+- **Screens are tracked automatically**, from the URL, including single-page route changes. An `AppticsScreenTracker.inScreen()` called from your router replaces the automatic view of that navigation, so nothing is counted twice; `track_screen: false` turns automatic tracking off. Each screen view now records how long it lasted.
+- **Events and properties follow the Android rules**: an event with an invalid group is not logged (a missing group is still `default`), names and keys may not start with `ap_`, and a bad property is dropped on its own rather than taking the others with it. Booleans arrive as Boolean, and `1` / `0` as Number.
+- Calling `Apptics.init()` a second time is ignored; use `reset()` to start over.
+- `Apptics.init()` still returns at once, but start-up finishes a few milliseconds later, once storage loads, so `window.appticsReady()` fires slightly later than in 1.0.2. Calls made in between are queued and replayed; `await apptics.ready()` waits for it.
+- `sendFeedback()` returns a Promise and takes `includeLog` as a sixth argument. `includeLog` and `includeDyninfo` are three-way: `true` always sends that file, `false` never does, and leaving it unset sends it when something is stored. The form's own log and diagnostics toggles and its data viewer are gone.
+- `dyninfo.txt` carries the diagnostics entries and a `[Device Info]` block. Stored feedback logs and diagnostics are capped at 1,000 entries and 10,000 characters per message.
+- The feedback form works without the Quartz script; the screen-recording option is hidden instead.
+- Clicks tracked with `apeventaction` no longer need jQuery.
+- Data moves from localStorage to IndexedDB on the first visit (device identity, consent, unsent events, feedback log entries), and the old keys are removed. Where IndexedDB is unavailable, the SDK keeps using localStorage.
+- Queued data is sent when the page is hidden or closed, using `pagehide` / `visibilitychange` instead of `beforeunload`.
+- New, and off until you use them: heatmaps, remote config, API tracking, the app logger, and the SDK's own failure reports to the Remote Logger page (`remote_log: true`). Remote config, once imported, fetches its values on start-up.
+
 ## License
 
-MIT © Zoho Apptics
+© Zoho Corporation Private Limited. The SDK is licensed for use in your websites and web applications with Zoho Apptics; the full terms are in the package's LICENSE file.