@heycatch/sdk 0.7.0 → 0.7.1-dev.1123

package/README.md

@@ -5,6 +5,88 @@ The official [HeyCatch](https://heycatch.ai) package for your app.
 _(AI Agents: the setup guide is https://heycatch.ai/agents.md - you also need
 the project key from the user's HeyCatch dashboard Install page.)_
 
+## Privacy & consent options
+
+`init()` accepts optional privacy/consent options alongside `projectKey`. Every
+one is unset by default, and each takes effect only when you set it - so
+`init({ projectKey })` on its own captures exactly as it always has:
+
+```ts
+analytics.init({
+  projectKey: 'hck_pk_...',
+  autocapture: false, // turn off automatic click/form-submit capture (pageviews and rage-clicks are captured separately, unaffected)
+  maskAllText: true, // strip captured elements' text content
+  maskAllElementAttributes: true, // strip captured elements' attributes
+  propertyDenylist: ['some_property'], // drop specific properties from every event (HeyCatch's own attribution keys can't be denylisted)
+  beforeSend: event => event, // runs on every event right before it's queued; return null to drop it
+  persistence: 'localStorage', // where the distinct id + super properties are stored
+  disablePersistence: false, // disable persistence entirely
+  cookieExpirationDays: 365, // days before the persistence cookie expires
+  optOutCapturingByDefault: true, // start with capturing off - see below
+  respectDnt: true, // honor the browser's Do Not Track signal
+});
+```
+
+In the browser, setting `autocapture: false`, `maskAllText: true`, or
+`maskAllElementAttributes: true` logs a one-line console notice naming what
+it costs you in the dashboard. (The other entries ignore these options, so
+they have nothing to warn about - see the platform notes below.)
+
+### Consent gate
+
+Set `optOutCapturingByDefault: true` to capture nothing until your visitor
+agrees (behind a cookie banner, for example), then:
+
+```ts
+analytics.optInCapturing(); // consent granted - start capturing
+analytics.optOutCapturing(); // consent withdrawn - stop again
+```
+
+While the gate is closed nothing is written to browser storage either, so no
+identifier lands before consent - not just "no events sent".
+
+Call `init()` before either one. Neither is remembered if it runs first -
+there is no transport yet to carry the decision - and both warn on the
+console when that happens rather than failing quietly. `init()`'s own config
+always wins, so a call made too early can never silently flip
+`optOutCapturingByDefault` back on.
+
+`optInCapturing` / `optOutCapturing` exist on every entry, so shared code
+compiles everywhere. They are a real gate in the browser and in React
+Native. On the server they are no-ops: a server event has no ambient visitor
+to consent for - each one already names its `userId` and only happens
+because your code called it.
+
+The remaining options above are browser behaviour. React Native honours
+`optOutCapturingByDefault`; the rest describe a DOM and a browser store it
+does not have. The server entry accepts the same `HeyCatchConfig` so one
+object works under every import condition, and ignores them.
+
+## Delivery options
+
+By default the SDK batches captured events for a few seconds before sending
+them, which is right for a single-page app. On a **multi-page site** - one
+where each click is a full page load - a visitor can navigate away inside
+that window, and iOS Safari in particular does not reliably let the batch out
+as the page is torn down. The symptom is mobile pageviews missing from your
+dashboard while desktop looks fine. Two options, both browser-only and both
+unset by default:
+
+```ts
+analytics.init({
+  projectKey: 'hck_pk_...',
+  requestBatching: false, // send every event as it happens - the fix for multi-page sites
+  flushIntervalMs: 250, // or keep batching but shrink the window (250-5000 ms; default 3000)
+});
+```
+
+Set one or the other - with batching off the interval has nothing to act on.
+The cost is one request per captured event, and autocapture is on by default:
+the count follows how much a visitor clicks, not how many pages they open, so a
+busy page sends more requests than a quiet one. `flushIntervalMs: 250` is the
+middle ground - still batched, but a window short enough that a navigation
+rarely lands inside it.
+
 ## License
 
 MIT