@heycatch/sdk 0.8.3 → 0.8.4-dev.2561

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
@@ -59,6 +86,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