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

package/README.md

@@ -1,25 +1,860 @@
-# @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 `base_url`, `auth_key` and `app_domain`. You also need your app's `appversion`.
+
+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.1
+```
+
+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 [Migrating from 1.0.2 to 2.0.0-beta.1](#migrating-from-102-to-200-beta1).
+
+## 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, AppticsEvent } from '@zoho_apptics/apptics-js-sdk';
+
+// Your web app's Apptics configuration, from the Apptics web console
+const appticsConfig = {
+  base_url: 'YOUR_BASE_URL',
+  auth_key: 'YOUR_AUTH_KEY',
+  app_domain: 'YOUR_APP_DOMAIN',
+  appversion: 'YOUR_APPVERSION',   // your app's version
+};
+
+// Initialize Apptics. Screens are tracked from the URL from here on, route changes included
+Apptics.init(appticsConfig);
+
+AppticsEvent.addEvent('signup', 'onboarding', { plan: 'pro' });
+```
+
+The config object is **required**, with `base_url`, `auth_key`, `app_domain` 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()`.
+
+Every call belongs to an object, named after its feature, so you import only the object and code reads much as it does on Android: `Apptics.init()`, `AppticsEvent.addEvent()`, `AppticsError.trackError()`, `AppticsFeedback.feedbackFormOpen()`. See [The API at a glance](#the-api-at-a-glance). 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 feedback
+form's styles are inside the build, so there is no stylesheet to add.
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@zoho_apptics/apptics-js-sdk@2.0.0-beta.1/dist/apptics.min.js"></script>
+<script>
+  Apptics.init({
+    base_url: 'YOUR_BASE_URL',
+    auth_key: 'YOUR_AUTH_KEY',
+    app_domain: 'YOUR_APP_DOMAIN',
+    appversion: 'YOUR_APPVERSION',   // your app's version
+  });
+  // screens are tracked from the URL automatically; events are yours to send
+  AppticsEvent.addEvent('signup', 'onboarding', { plan: 'pro' });
+</script>
+```
+
+The build defines the same objects as globals (`Apptics`, `AppticsEvent`, `AppticsScreen`, `AppticsApi`, `AppticsError`, `AppticsUser`, `AppticsSettings`, `AppticsFeedback`, `AppticsLogger`, `AppticsRemoteConfig`, `AppticsHeatmap`), so a page's code reads as it would after an import. Every module is included (feedback, heatmaps, remote config, the remote logger), and everything is also on `window.apptics`. 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.1`) 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.
+
+### The API at a glance
+
+Each feature's calls are on one object:
+
+| Object | Calls | Entry point |
+|---|---|---|
+| `Apptics` | `init(config)`, `ready()`, `flush()`, `reset()`, `enableDebug()`, `disableDebug()` | main |
+| `AppticsEvent` | `addEvent(eventName, groupName?, properties?)`, `addEvent(DefinedEvents.X, properties?)`, `DefinedEvents` | main |
+| `AppticsScreen` | `inScreen(screenName, properties?)` → id, `outScreen(id)` | main |
+| `AppticsError` | `trackError(error, properties?)`, `trackGlobalErrorHandler(enabled?)` | main |
+| `AppticsUser` | `setUser(userid, groupid?, properties?)`, `getUser()`, `UserBuilder` | main |
+| `AppticsSettings` | `setTrackingStatus(status)`, `getTrackingStatus()`, the `AP_TRACKING_STATUS` constants | main |
+| `AppticsApi` | `startTrackApi(url, method?)` → id, `endTrackApi(id, responseCode, responseMessage?)`, `configure(config)`, `enableApiTracking(enabled?)`, `ApiTrackingBuilder` | main |
+| `AppticsHeatmap` | `trackHeatmap(on?)` | main |
+| `AppticsLogger` | `verbose(message, properties?)`, `debug(message, properties?)`, `info(message, properties?)`, `warn(message, properties?)`, `error(message, properties?)` | `/remote-logger` |
+| `AppticsFeedback` | `feedbackFormOpen(options?)`, `feedbackFormClose()`, `sendFeedback(options?)`, `addFeedbackLog(message)`, `addDiagnosticsInfo(heading, key, value)`, `setFeedbackTheme(theme)`, the `AP_FEEDBACK_TYPE` constants | `/feedback` |
+| `AppticsRemoteConfig` | `fetchValue(name, callback?)`, `fetchValues(names?, callback?)`, `setCustomConditionValue(conditionname, value)` | `/remote-config` |
+
+The package exports only these objects: `DefinedEvents` is `AppticsEvent.DefinedEvents`, and the builders are `AppticsApi.ApiTrackingBuilder` and `AppticsUser.UserBuilder`. Android's `AppticsScreenTracker` and `AppticsApiTracker` are `AppticsScreen` and `AppticsApi` here.
+
+### 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 `AppticsScreen.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 => AppticsScreen.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 | `AppticsScreen.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 { AppticsError } from '@zoho_apptics/apptics-js-sdk';
+
+try {
+  doSomething();
+} catch (error) {
+  AppticsError.trackError({ type: 'error', error });
+}
+```
+
+`AppticsError.trackError` also accepts `error` and `unhandledrejection` events as they are, and properties as a second argument. Turn the automatic tracking off with `AppticsError.trackGlobalErrorHandler(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) { AppticsError.trackError({ type: 'error', error }); }` |
+| Vue 3, Nuxt 3 | `app.config.errorHandler = (error) => AppticsError.trackError({ type: 'error', error })` (Nuxt: `nuxtApp.hook('vue:error', …)`) |
+| Angular | an `ErrorHandler` whose `handleError(error)` calls `AppticsError.trackError({ type: 'error', error })`, provided as `{ provide: ErrorHandler, useClass: … }` |
+| SvelteKit | `handleError({ error })` in `src/hooks.client.ts` |
+| Ember | `Ember.onerror = (error) => AppticsError.trackError({ type: 'error', error })` |
+
+## Event Tracking
+
+Track an event, with an optional group and properties:
+
+```ts
+import { AppticsEvent } from '@zoho_apptics/apptics-js-sdk';
+
+AppticsEvent.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 { AppticsEvent } from '@zoho_apptics/apptics-js-sdk';
+
+const { DefinedEvents } = AppticsEvent;
+
+AppticsEvent.addEvent(DefinedEvents.AP_USER_LOGIN);
+AppticsEvent.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 `AppticsEvent.DefinedEvents` too.
+
+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`. The
+`data-` spellings work too (`data-apeventaction`, `data-apgroupaction`, `data-apeventprops`), which
+React and TypeScript accept as they are.
+
+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 `AppticsScreen.inScreen`, as on Android:
+
+```ts
+import { AppticsScreen } from '@zoho_apptics/apptics-js-sdk';
+
+AppticsScreen.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.
+`AppticsScreen.inScreen` returns the view's id; hand it to `AppticsScreen.outScreen` to end the view yourself (a dialog
+that closes without the page changing, say), as Android's `AppticsScreenTracker.outScreen` does:
+
+```ts
+import { AppticsScreen } from '@zoho_apptics/apptics-js-sdk';
+
+const id = AppticsScreen.inScreen('settings');   // when the screen is shown
+AppticsScreen.outScreen(id);                        // when it is dismissed
+```
+
+`AppticsScreen.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 `AppticsScreen.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 `AppticsScreen.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 `AppticsScreen.inScreen()` call made during a navigation, from a router hook for example,
+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 `AppticsScreen.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. `screen_routes` names them instead. Each
+entry is one of three kinds, tried in order; the first that matches names the screen, and a path
+none matches keeps its own name:
+
+| Entry | Matches | Recorded as |
+|---|---|---|
+| `'/users/{id}/orders'` | a route pattern: `{id}`, `:id` and `*` each match one path segment | the pattern, each variable segment as `*` |
+| `{ equals: '/', name: 'Home' }` | that path exactly (a trailing slash does not matter) | `name` |
+| `{ regex: /^\/orders\/\d+$/, name: 'Order detail' }` | any path the regular expression matches (a `RegExp` or its source as a string) | `name` |
+
+```ts
+Apptics.init({
+  ...config,
+  screen_routes: [
+    { equals: '/', name: 'Home' },
+    { regex: /^\/orders\/\d+$/, name: 'Order detail' },
+    '/users/{id}/{id}/orders',
+    '/products/:sku',
+  ],
+});
+```
+
+| Opened | Recorded as |
+|---|---|
+| `/` | `Home` |
+| `/orders/123?tab=items` | `Order detail` (paths are matched without the query string) |
+| `/users/12/34/orders` | `/users/*/*/orders` |
+| `/products/sku-889` | `/products/*` |
+| `/users/12/34/settings` | `/users/12/34/settings` (no entry matches, so the name is kept) |
+
+An entry that can't be used (no `name`, a regex that does not compile) is left out, and
+`Apptics.init()` says which in the console.
+
+**An app that names its screens from its router** keeps doing so with `AppticsScreen.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 });
+```
+
+`Apptics.reset()` takes the history wrappers off; the `Apptics.init()` it runs puts them back.
+
+## Track User
+
+Register the signed-in user:
+
+```ts
+import { AppticsUser } from '@zoho_apptics/apptics-js-sdk';
+
+AppticsUser.setUser('user-id', 'customer-group-id');   // the group is optional
+```
+
+`AppticsUser.setUser` switches tracking to "with PII" (see [Tracking settings](#tracking-settings)). `AppticsUser.getUser()` returns the active user.
+
+### Track User with properties
+
+```ts
+import { AppticsUser } from '@zoho_apptics/apptics-js-sdk';
+
+const properties = new AppticsUser.UserBuilder()
+  .setFirstName('Ana')
+  .setEmailAddress('ana@zylker.com')
+  .setPlanType('pro')
+  .setCustomProperties({ team: 'design' })
+  .build();
+
+AppticsUser.setUser('user-id', 'customer-group-id', properties);
+```
+
+The builder also has `setLastName`, `setCompanyName`, `setContactNumber`, `setCountry`, `setRegion`, `setCity`, `setGeoLocation`, `setGender`, `setTimezone`, `setLanguage`, `setEngagementScore` and `setDateOfBirth`, and `addStringProperty(key, value)`,
+`addNumberProperty` and `addBooleanProperty` for one custom property at a time. `build()` validates the properties against what the server accepts.
+
+## Tracking settings
+
+Set what the SDK may track for this visitor:
+
+```ts
+import { AppticsSettings } from '@zoho_apptics/apptics-js-sdk';
+
+AppticsSettings.setTrackingStatus(AppticsSettings.AP_TRACKING_STATUS.USAGE_TRACKING_WITHOUT_PII);
+```
+
+| `AppticsSettings.AP_TRACKING_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 |
+
+`AppticsSettings.getTrackingStatus()` returns the current one.
+
+### 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`, `apeventaction` or `data-apeventaction`, `aria-label`, `name`, `id`, `title`); its visible text is used only with `USAGE_TRACKING_WITH_PII`.
+
+## API Tracking
+
+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
+```
+
+`AppticsApi.enableApiTracking(enabled)` switches it later. Which hosts and endpoints are recorded is set with
+[`AppticsApi.configure`](#configuring-api-tracking).
+
+or record calls yourself with `AppticsApi.startTrackApi` / `endTrackApi`, as on Android. The
+SDK times the call between the two:
+
+```ts
+import { AppticsApi } from '@zoho_apptics/apptics-js-sdk';
+
+const id = AppticsApi.startTrackApi('https://api.example.com/orders/42', 'GET');
+const response = await fetch('https://api.example.com/orders/42');
+AppticsApi.endTrackApi(id, response.status, response.statusText);
+```
+
+Between them, automatic tracking and `AppticsApi.startTrackApi` / `endTrackApi` are the
+two ways a call is recorded.
+
+### Configuring API tracking
+
+Build the rules with `AppticsApi.ApiTrackingBuilder` (as `AppticsUser.UserBuilder` builds user
+properties) and apply them once, before the requests they should cover. It works before
+`Apptics.init()`:
+
+```ts
+import { AppticsApi } from '@zoho_apptics/apptics-js-sdk';
+
+AppticsApi.configure(new AppticsApi.ApiTrackingBuilder()
+  .allowRegex(/^https:\/\/api\.yourapp\.(com|in|ae)\//)       // only your API hosts
+  .allowEquals('https://auth.yourapp.com/token')               // and this one endpoint
+  .ignoreEquals('https://api.yourapp.com/health')              // never this one
+  .ignoreRegex(/\/internal\//)                                 // nor anything under /internal/
+  .build());
+```
+
+Four rules, two kinds by two: an exact URL (`Equals`) or a regular expression (`Regex`), to allow
+or to ignore. Each is tried on the call's URL as `scheme://host[:port]/path`, without its query
+string or fragment, so one rule can name a host, a path or a single endpoint.
+
+| Builder call | Effect |
+|---|---|
+| `allowEquals(...urls)` | Record these URLs exactly, as `'https://api.yourapp.com/orders'` |
+| `allowRegex(...patterns)` | Record the URLs these regular expressions match, as `/^https:\/\/api\.yourapp\.com\//` |
+| `ignoreEquals(...urls)` | Never record these URLs exactly |
+| `ignoreRegex(...patterns)` | Never record the URLs these regular expressions match |
+
+- **Ignore always wins.** Ignore rules are tried first; then, when there are any allow rules, a call
+  must match one of them. With no rules at all, every call is recorded.
+- **Equals** compares whole URLs: the scheme and host are not case-sensitive, a trailing slash and
+  the default port do not matter, a port that is not the default does. It takes full URLs only.
+- **Regex** takes a `RegExp` or its source as a string, and works with any flags.
+- A URL that is not a full http(s) URL, or a regex that does not compile, is left out and the
+  console says why. A second `AppticsApi.configure()` replaces the first.
+
+The rules apply to every call, the ones `track_api` catches and the ones you report yourself.
+
+**Path normalization**, always on, 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) |
+
+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. `AppticsApi.enableApiTracking(false)` removes the wrappers again.
+With a `<script>` tag, `AppticsApi` is a global as it is here, `AppticsApi.ApiTrackingBuilder`
+included.
+
+## 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';
+
+const banner = await AppticsRemoteConfig.fetchValue('bannerText');         // null if there is none
+const some = await AppticsRemoteConfig.fetchValues(['primaryColor', 'maxItems']);
+// → { primaryColor: '#0b6e4f', maxItems: '10' }
+const all = await AppticsRemoteConfig.fetchValues();                       // every parameter
+
+// for a custom condition: its name, then this device's values, comma separated
+AppticsRemoteConfig.setCustomConditionValue('is_custom', 'custom_color');
+```
+
+A name the console doesn't have is `null`.
+
+**How a value is chosen.** The SDK goes through the conditions in the order the console lists them
+(`all_condition`), skipping those that don't apply to the parameter. The first one that matches
+this device gives the parameter's value for it; when none matches, the parameter's default value.
+A condition matches when all of its criteria match this device.
+
+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; once
+that fetch is older, the next call asks the server. 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;
+with none fetched yet, `null` (and `fetchValues()` answers with no parameters).
+
+**Custom conditions.** `setCustomConditionValue(conditionname, value)` says what this device is
+for the custom condition with that name in the console, with several values comma separated
+(`'gold,platinum'`). The condition matches when one of them is one of the values it lists. The
+stored rules are applied again at once, without a fetch; an empty value removes it. Values are for
+this page, so set them as the app starts; it works before `Apptics.init()`, and `Apptics.reset()`
+clears them.
+
+Conditions on the user, such as the customer group, are re-applied on their own once
+`AppticsUser.setUser` has registered the user, so the next read answers for them.
+
+| Call | Notes |
+|---|---|
+| `fetchValue(name, callback?)` | One parameter for this session; `null` when the console has none. |
+| `fetchValues(names?, callback?)` | The parameters named in the list, `null` for a missing one; with no names, every parameter. `fetchValues(callback)` works too. |
+| `setCustomConditionValue(conditionname, value)` | This device's values for a custom condition, comma separated (`'gold,platinum'`); an empty value removes them. |
+
+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`, from its own
+entry point (`@zoho_apptics/apptics-js-sdk/remote-logger`) so apps that don't log don't ship it.
+Nothing is logged on its own: only the lines your app writes, at five levels, as Android's
+`v` / `d` / `i` / `w` / `e` with their names in full. A line is recorded as it is written, with no
+switch to turn on first:
+
+```ts
+import { AppticsLogger } from '@zoho_apptics/apptics-js-sdk/remote-logger';
+
+AppticsLogger.verbose('Cache warmed');
+AppticsLogger.debug('Cart loaded', { items: 3 });
+AppticsLogger.info('Payment started', { orderId: 42, method: 'card' });
+AppticsLogger.warn('Retrying the payment', { attempt: 2 });
+AppticsLogger.error('Payment failed', err);          // an Error as properties: sent with its stack
+```
+
+| Call | Level on the Remote Logger page |
+|---|---|
+| `AppticsLogger.verbose(message, properties?)` | 1, Verbose |
+| `AppticsLogger.debug(message, properties?)` | 2, Debug |
+| `AppticsLogger.info(message, properties?)` | 3, Info |
+| `AppticsLogger.warn(message, properties?)` | 4, Warning |
+| `AppticsLogger.error(message, properties?)` | 5, Error |
+
+`properties` is appended to the message: an object as JSON (`Payment started {"orderId":42,"method":"card"}`),
+an `Error` as its stack. 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 for the app, or while tracking is off.
+
+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.
+
+## In-App Feedback
+
+The feedback form is its own entry point, so apps that don't use it don't download it. Its
+`AppticsFeedback` has every feedback call: the form, sending without it, and the log and
+diagnostics calls. With a `<script>` tag it is the `AppticsFeedback` global.
+
+### Show feedback screen
+
+```ts
+import { AppticsFeedback } from '@zoho_apptics/apptics-js-sdk/feedback';
+
+AppticsFeedback.feedbackFormOpen();     // show the form
+AppticsFeedback.feedbackFormClose();    // close it from your own code, when needed
+```
+
+`feedbackFormOpen` takes one options object, which fills the form in for the visitor. Every key is
+optional:
+
+```ts
+AppticsFeedback.feedbackFormOpen({
+  type: AppticsFeedback.AP_FEEDBACK_TYPE.BUG,  // the tab it opens on: BUG, FEEDBACK, HELP or REPORT
+  message: 'The checkout button does nothing', // text already in the description
+  includeLog: true,                            // start with the log toggle on
+  includeDiagnostics: true,                    // start with the diagnostics toggle on
+  attachments: [screenshotFile],               // files already attached (a FileList or File[])
+  logFiles: [appLogFile],                      // log files already attached
+  isAnonymous: false,                          // true starts the user picker on Anonymous
+});
+```
+
+Passing values one after another, as `feedbackFormOpen(type, message)`, opens the form with its
+defaults and a console warning.
+
+The form brings its own styles, with the npm package and the CDN builds alike: the first
+`feedbackFormOpen()` adds them to the page, so there is no stylesheet to import or link.
+
+**Theme:** the form is `light`, `dark`, or `auto` (the default), which follows the visitor's system setting:
+
+```ts
+Apptics.init({ ...config, feedback_theme: 'dark' });
+```
+
+`auto` follows the operating system, not the page. A page with its own light and dark modes tells
+the form which one it shows, whenever that changes; a form that is open is restyled at once:
+
+```ts
+AppticsFeedback.setFeedbackTheme(isDark ? 'dark' : 'light');
+```
+
+The colors are CSS variables on the form, so a page can restyle it without any SDK option. Override them
+where the form is shown, for example to set a brand color:
+
+```css
+.zasdk-modal { --zasdk-primary-color: #0b5d8f; }
+```
+
+The main ones are `--zasdk-background-color`, `--zasdk-text-color`, `--zasdk-border-color`,
+`--zasdk-input-background`, `--zasdk-primary-color` (the Send button), `--zasdk-button-text-color`,
+`--zasdk-link-color` and `--zasdk-shadow`.
+
+The form is a modal dialog for keyboards and screen readers: it takes focus when it opens, Escape or
+the close control (with Enter or Space) closes it, and it honours `prefers-reduced-motion`.
+
+The form offers Feedback (selected by default), Bug, Help and Report, with up to 5 attachments (10 MB total).
+
+### Send Feedback/Bug Report programmatically
+
+```ts
+import { AppticsFeedback } from '@zoho_apptics/apptics-js-sdk/feedback';
+
+try {
+  await AppticsFeedback.sendFeedback({
+    type: AppticsFeedback.AP_FEEDBACK_TYPE.BUG,  // BUG (0), FEEDBACK (1, the default), HELP (2), REPORT (3)
+    message: 'Checkout is broken',
+    attachments: [screenshotFile],               // at most 5, 10 MB in all
+    includeLog: true,                            // the addFeedbackLog() lines
+    includeDiagnostics: true,                    // the addDiagnosticsInfo() entries and the device details
+    isAnonymous: false,                          // true sends it from nobody
+  });
+  // sent
+} catch (err) {
+  // not sent: the SDK hasn't started (no Apptics.init()), the browser is offline, or the server refused it
+}
+```
+
+`AppticsFeedback.sendFeedback(options?)` takes `type`, `message`, `attachments`, `logFiles`,
+`includeDiagnostics`, `includeLog` and `isAnonymous`, all optional. It is sent from the user
+`AppticsUser.setUser` set, or from nobody with `isAnonymous: true`. It returns a Promise that resolves once the
+feedback is sent and rejects when it wasn't. Passing values one after another, as
+`sendFeedback(type, message)`, rejects rather than send an empty report.
+
+Feedback is sent even when tracking is off (`NO_TRACKING`): the visitor is choosing to send it.
+Only the feedback goes; nothing else is tracked.
+
+### Attach logs and diagnostics with Feedback
+
+```ts
+import { AppticsFeedback } from '@zoho_apptics/apptics-js-sdk/feedback';
+
+AppticsFeedback.addFeedbackLog('token refresh failed, retrying');       // one timestamped line
+AppticsFeedback.addDiagnosticsInfo('Auth', 'scheme', 'oauth');          // grouped key/value
+AppticsFeedback.addDiagnosticsInfo('Auth', 'expiry', 3600);
+```
+
+`addDiagnosticsInfo` needs all three: a heading, a key and a value (`0` and `false` count). An
+entry without one is not recorded, and the console says why.
+
+Both calls are on the `/feedback` entry's `AppticsFeedback`, which is where every feedback call
+lives; the main entry point has no `AppticsFeedback`. 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 `includeDiagnostics` 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. It is on the
+main entry point and off until you turn it on.
+
+```ts
+import { Apptics, AppticsHeatmap } from '@zoho_apptics/apptics-js-sdk';
+
+Apptics.init({ ...config, track_heatmap: true });
+// or turn it on later: AppticsHeatmap.trackHeatmap(true)
+```
+
+`track_heatmap: true` in `Apptics.init()` starts capture with the SDK. With a `<script>` tag it's
+`AppticsHeatmap.trackHeatmap()` on the `AppticsHeatmap` global.
+
+| Call | Notes |
+|---|---|
+| `AppticsHeatmap.trackHeatmap(on?)` | Starts or stops capture; `on` defaults to `true`. |
+
+Heatmap records go out with the rest of the stored data: on the flush timer, or when you call
+`Apptics.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
+
+Debug mode is off by default; you follow it in the Apptics web console.
+
+### 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
+Apptics.enableDebug();    // turn debug mode on
+Apptics.disableDebug();   // and off again
+```
+
+`Apptics.enableDebug()` and `Apptics.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 `Apptics.reset()`, so a page whose config turns
+debug mode on can still switch it off with `Apptics.disableDebug()`. With a `<script>` tag they are
+the same calls on the `Apptics` global.
+
+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 `Apptics.enableDebug()` or `Apptics.disableDebug()`. |
+| `Apptics.enableDebug()` / `Apptics.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. |
+
+## Configuration
+
+Everything `Apptics.init(config)` accepts.
+
+| Key | Required | Description |
+|---|---|---|
+| `base_url` | yes | The Apptics host every request goes to, from the Apptics web console (a trailing slash is ignored) |
+| `auth_key` | yes | The app's auth key, from the Apptics web console |
+| `app_domain` | yes | The app's domain registered in the Apptics web console, e.g. `com.zylker.web` |
+| `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)). Off by default |
+| `ignore_do_not_track` | | Track even when the browser sends Do Not Track. Off by default |
+| `track_api` | | Record the app's own fetch and XHR calls. Off by default; which hosts and endpoints, through `AppticsApi.configure` (see [API Tracking](#api-tracking)) |
+| `track_heatmap` | | Record clicks and scrolls (see [Heatmaps](#heatmaps)). Off by default |
+| `heatmap_max_per_session` | | Most heatmap records one visit may produce: 500 by default, 0 to 10000. Capture pauses past it |
+| `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)) |
+| `screen_routes` | | How automatic screen tracking names a path: route patterns (`'/users/{id}/orders'`), `{ equals, name }` and `{ regex, name }` rules, tried in order (see [Automatic screen tracking](#automatic-screen-tracking)) |
+| `feedback_theme` | | The feedback form's theme: `'light'`, `'dark'` or `'auto'` (the default, which follows the visitor's system setting). See [Show feedback screen](#show-feedback-screen) |
+| `device_name` | | Names this device in debug mode (see [Debugging](#debugging)) |
+
+The earlier names still work, with a console warning naming the key to use: `serviceUrl` and
+`base_domain` for `base_url`, `zak` and `token` for `auth_key`, and `identifier` for `app_domain`.
+`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 to 3600000 | How often stored data is sent, in milliseconds |
+| `getupdates_interval` | `120000` | 10000 to 86400000 | How often the server's tracking settings are checked, in milliseconds; the server can ask for a longer wait |
+| `batch_size` | `50` | 1 to 500 | Most items in one request (also capped at 1 MB) |
+| `batch_request_timeout` | `7` | 1 to 30 | Days an unsent item is kept before it is dropped |
+| `inactiveduration` | `30` | 1 to 1440 | Idle minutes that end a session |
+| `min_session_duration` | `5000` | 0 to 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 `Apptics.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. |
+| `Apptics.ready()` | Promise that resolves `true` once the SDK is running (`false` if it can't start). |
+| `AppticsEvent.addEvent(eventName, groupName?, properties?)` / `AppticsEvent.addEvent(AppticsEvent.DefinedEvents.X, properties?)` | See [Event Tracking](#event-tracking). |
+| `AppticsScreen.inScreen(screenName, properties?)` → id / `AppticsScreen.outScreen(id)` | See [Screen Tracking](#screen-tracking). |
+| `AppticsError.trackError(error, properties?)` / `AppticsError.trackGlobalErrorHandler(enabled?)` | See [Error Tracking](#error-tracking). |
+| `AppticsUser.setUser(userid, groupid?, properties?)` / `AppticsUser.getUser()` / `AppticsUser.UserBuilder` | See [Track User](#track-user). |
+| `AppticsSettings.setTrackingStatus(status)` / `AppticsSettings.getTrackingStatus()` / `AppticsSettings.AP_TRACKING_STATUS` | See [Tracking settings](#tracking-settings). |
+| `AppticsApi.startTrackApi(url, method?)` / `endTrackApi(id, responseCode, responseMessage?)` / `configure(config)` / `enableApiTracking(enabled?)` / `AppticsApi.ApiTrackingBuilder` | See [API Tracking](#api-tracking). |
+| `AppticsLogger.verbose / debug / info / warn / error(message, properties?)` | From `/remote-logger`; see [Remote Logger](#remote-logger). |
+| `AppticsRemoteConfig.fetchValue(name, callback?)` / `fetchValues(names?, callback?)` / `setCustomConditionValue(conditionname, value)` | From `/remote-config`; see [Remote Config](#remote-config). |
+| `AppticsFeedback.addFeedbackLog(message)` / `AppticsFeedback.addDiagnosticsInfo(heading, key, value)` | From `/feedback`; see [Attach logs and diagnostics](#attach-logs-and-diagnostics-with-feedback). |
+| `AppticsFeedback.feedbackFormOpen(options?)` / `feedbackFormClose()` / `sendFeedback(options?)` / `setFeedbackTheme(theme)` / `AppticsFeedback.AP_FEEDBACK_TYPE` | From `/feedback`; see [In-App Feedback](#in-app-feedback). |
+| `AppticsHeatmap.trackHeatmap(on?)` | See [Heatmaps](#heatmaps). |
+| `Apptics.flush()` | Send stored data now (engagement, errors and heatmap records); it's otherwise sent every 30 s (see [Timing](#timing)). |
+| `Apptics.enableDebug()` / `Apptics.disableDebug()` | See [Debugging](#debugging). |
+| `Apptics.reset()` | Clear stored identity, queued data and remote config values, then start again. |
+
+Entry points: `@zoho_apptics/apptics-js-sdk` (everything above except what follows), `/feedback`, `/remote-config`
+(see [Remote Config](#remote-config)), `/remote-logger` (see [Remote Logger](#remote-logger)). 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, AppticsEvent } from 'https://cdn.jsdelivr.net/npm/@zoho_apptics/apptics-js-sdk@2.0.0-beta.1/dist/apptics.esm.min.js';
+  // The feedback form is a separate file, so pages without it don't download it
+  import { AppticsFeedback } from 'https://cdn.jsdelivr.net/npm/@zoho_apptics/apptics-js-sdk@2.0.0-beta.1/dist/feedback.esm.min.js';
+
+  Apptics.init({
+    base_url: 'YOUR_BASE_URL',
+    auth_key: 'YOUR_AUTH_KEY',
+    app_domain: 'YOUR_APP_DOMAIN',
+    appversion: 'YOUR_APPVERSION',   // your app's version
+  });
+  // screens are tracked from the URL automatically
+  AppticsEvent.addEvent('signup', 'onboarding', { plan: 'pro' });
+</script>
 ```
 
-#### intialization 
+| File | For | Size (gzipped) |
+|---|---|---|
+| `dist/apptics.min.js` | `<script>` pages; sets `window.apptics`, includes every module | ~53 kB |
+| `dist/apptics.esm.min.js` | `<script type="module">`; analytics only (with the `dist/chunks/` files it imports) | ~30 kB |
+| `dist/feedback.esm.min.js` | the feedback form, for module pages | ~17 kB more |
 
-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.
+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.1/dist/apptics.min.js`. Add `defer` if you don't need the SDK before the page renders. For a subresource-integrity hash:
 
-## Usage
+```bash
+curl -s https://cdn.jsdelivr.net/npm/@zoho_apptics/apptics-js-sdk@2.0.0-beta.1/dist/apptics.min.js \
+  | openssl dgst -sha384 -binary | openssl base64 -A
+```
 
-```javascript
-const Apptics = require('@zoho_apptics/apptics-js-sdk');
+```html
+<script src="…/apptics.min.js" integrity="sha384-…" crossorigin="anonymous"></script>
 ```
 
+## Migrating from 1.0.2 to 2.0.0-beta.1
+
+### What you need to change
+
+- **Every call is on the object of its feature.** Rename them everywhere, router hooks included: a
+  call to an old name left in place throws.
+
+  | 1.0.2 | 2.0.0-beta.1 |
+  |---|---|
+  | `apptics.init(config)` | `Apptics.init(config)` |
+  | `apptics.trackEvent(name, group, props)` | `AppticsEvent.addEvent(eventName, groupName, properties)` |
+  | `apptics.trackScreen(name, props)` | `AppticsScreen.inScreen(screenName, properties)`, which also returns the view's id for `AppticsScreen.outScreen(id)` |
+  | `apptics.trackError(event, props)` | `AppticsError.trackError(error, properties)` |
+  | `apptics.enableGlobalErrorHandler(on)` | `AppticsError.trackGlobalErrorHandler(enabled)` |
+  | `apptics.setUser(userid, groupid, props)` | `AppticsUser.setUser(userid, groupid, properties)` |
+  | `apptics.getUser()`, `new users.UserBuilder()` | `AppticsUser.getUser()`, `new AppticsUser.UserBuilder()` |
+  | `apptics.setTrackingStatus(s)`, `getTrackingStatus()` | `AppticsSettings.setTrackingStatus(status)`, `AppticsSettings.getTrackingStatus()` |
+  | `apptics.flush()`, `reset()`, `ready()` | `Apptics.flush()`, `Apptics.reset()`, `Apptics.ready()` |
+  | `apptics.feedbackOpen()`, `feedbackClose()` | `AppticsFeedback.feedbackFormOpen(options)`, `AppticsFeedback.feedbackFormClose()` |
+  | `apptics.sendFeedback(type, message, …)` | `AppticsFeedback.sendFeedback({ type, message, … })`: one options object |
+  | `apptics.addFeedbackLog()`, `addDiagnosticsInfo()` | `AppticsFeedback.addFeedbackLog(message)`, `AppticsFeedback.addDiagnosticsInfo(heading, key, value)` |
+
+- **`Apptics.init()` takes new config.** Pass `base_url`, `auth_key`, `app_domain` and `appversion`, all
+  required (1.0.2's `base_domain` and `token` still work, with a warning). 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({ base_url, auth_key, app_domain, appversion });
+  ```
+
+- **The optional modules are their own entry points for npm users**, so an app ships only what it
+  uses: `AppticsFeedback` from `/feedback` (every feedback call, logs and diagnostics included; the
+  form adds its own styles), `AppticsRemoteConfig` from `/remote-config` and `AppticsLogger` from
+  `/remote-logger`. The `<script>` build has everything, as globals and 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.
+- 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. Do Not Track is decided on every visit and never stored.
+- `mute()` and `unmute()` are gone. To stop tracking, use `AppticsSettings.setTrackingStatus(AppticsSettings.AP_TRACKING_STATUS.NO_TRACKING)`; unlike `mute()`, it is stored across visits. Feedback is still sent with tracking off.
+- **Screens are tracked automatically**, from the URL, including single-page route changes. An `AppticsScreen.inScreen()` called from your router replaces the automatic view of that navigation, so nothing is counted twice; `track_screen: false` turns automatic tracking off, and `screen_routes` names paths. 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. An invalid name is said in the console.
+- Calling `Apptics.init()` a second time is ignored; use `Apptics.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. A first visit with no network starts once the browser is back online.
+- `AppticsFeedback.sendFeedback()` returns a Promise. `includeLog` and `includeDiagnostics` are three-way: `true` always sends that file, `false` never does, and leaving it unset sends it when something is stored.
+- `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.
+- Clicks tracked with `apeventaction` (or `data-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 (`AppticsHeatmap.trackHeatmap()`), remote config, API tracking and the remote logger (`AppticsLogger`). 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.