@heycatch/sdk 0.8.3 → 0.8.5-dev.2545

package/README.md

@@ -5,6 +5,33 @@ 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.)_
 
+## Sign-in and sign-out
+
+Call `setIdentity` right after sign-in and `resetIdentity` on sign-out:
+
+```ts
+// After sign-in. A stable internal user id - never an email or a session
+// token. Email and name, if you send them, go in the properties.
+analytics.setIdentity(user.id, { email: user.email, name: user.name });
+
+analytics.resetIdentity(); // on sign-out, so the next person starts anonymous
+```
+
+Skip `resetIdentity` and the device keeps the signed-out user's identity.
+Everything the next person does before signing in is recorded as the
+previous user. On a shared device - a work tablet, a kiosk, a family
+computer - whoever uses it without signing in lands in the last signed-in
+user's profile, which then describes several people. HeyCatch's per-user summaries and recommendations are written from
+those profiles, so they end up describing someone who does not exist.
+
+`setIdentity` with a different user than the one already signed in resets
+on its own, so a direct account switch is safe. What it cannot know is that
+someone signed out and left: only your sign-out handler knows that.
+
+`resetIdentity` works in the browser and in React Native. On the server it
+is a no-op, so isomorphic sign-out code still resolves there - but the call
+has to run on the device to take effect.
+
 ## Privacy & consent options
 
 `init()` accepts optional privacy/consent options alongside `projectKey`. Every
@@ -24,6 +51,7 @@ analytics.init({
   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
+  collectIp: false, // don't store the visitor's IP address or their location - see below
 });
 ```
 
@@ -46,6 +74,54 @@ it was. This is always on, has no option, and runs after your `beforeSend`,
 so a hook cannot put a token back. It applies in the browser, in React
 Native, and on the server alike.
 
+### Visitor IP addresses
+
+Set `collectIp: false` and no event stores the visitor's IP address, and no
+country or city is derived from it. The address does not reach analytics
+storage at all: the SDK blanks it on every event, after your `beforeSend`,
+and HeyCatch's ingest drops it from the request too.
+
+It is decided per visitor, so if your banner asks about IP or location you
+can pass that answer straight through, and flip it when the visitor answers
+later:
+
+```ts
+// `=== true`: a visitor who has not answered yet is not collected either
+analytics.init({
+  projectKey: 'hck_pk_...',
+  collectIp: storedIpAnswer() === true,
+});
+
+// in your consent banner's handler
+analytics.setIpCollection(allowsIp); // false stops collecting from the next event
+```
+
+Nothing is remembered between page loads or app launches: pass the
+visitor's answer to `init()` every time. `setIpCollection()` before
+`init()` logs a warning and does nothing. Unset, or `true`, collects the
+IP as before. What `false` costs, and what it
+does not promise:
+
+- No country in your users table for new visitors, and no geo breakdowns
+  for those events. A returning visitor keeps the country already stored on
+  their profile from before.
+- It applies from the SDK version that has it. A mobile app needs a new
+  release, and app versions already on users' phones keep sending IPs.
+- It has to be set on every surface you ship - your site and your app each
+  have their own `init()`. One left out keeps sending IPs for that surface.
+- What you can tell your users is "we don't store your IP address or a
+  location derived from it" - for what they do after you turn it off; a
+  country already on a returning visitor's profile stays, and location you
+  send yourself in event or person properties is stored as you sent it.
+  Not "your analytics is anonymous":
+  the device id, and your own user id after `setIdentity`, stay on events.
+  If your banner asks for consent to analytics as a whole, that is the
+  [consent gate](#consent-gate) below, not this switch.
+
+It works in the browser and in React Native. The server entry accepts
+`collectIp` and `setIpCollection()` and ignores both: a server event's
+request comes from your server, not a visitor.
+
 ### Consent gate
 
 Set `optOutCapturingByDefault: true` to capture nothing until your visitor
@@ -59,6 +135,14 @@ 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".
 
+A visitor who arrives through one of your HeyCatch short links lands on a URL
+carrying `?utm_source=heycatch&utm_campaign=<letter>`. The SDK removes those
+from the address bar a second after the first capture has read them - and
+behind the gate, that first capture is the one `optInCapturing()` makes, so
+the URL stays as it is until then and the visit is still attributed after
+consent. Your own UTM links (any `utm_source` other than `heycatch`) are never
+touched.
+
 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
@@ -72,8 +156,8 @@ 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
+`optOutCapturingByDefault` and `collectIp`; 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