@heycatch/sdk 0.8.2-dev.1657 → 0.8.3-dev.2140

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
@@ -18,7 +45,7 @@ analytics.init({
   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
+  beforeSend: event => event, // runs on every event right before it's queued; return null to drop it (the SDK's own delivery and attribution keys are put back after it)
   persistence: 'localStorage', // where the distinct id + super properties are stored
   disablePersistence: false, // disable persistence entirely
   cookieExpirationDays: 365, // days before the persistence cookie expires