@heycatch/sdk 0.8.4-dev.2561 → 0.8.5-dev.2546

package/README.md

@@ -51,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
 });
 ```
 
@@ -73,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
@@ -107,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