@heycatch/sdk 0.8.1-dev.1579 → 0.8.3-dev.1682

package/README.md

@@ -18,7 +18,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
@@ -32,6 +32,20 @@ In the browser, setting `autocapture: false`, `maskAllText: true`, or
 it costs you in the dashboard. (The other entries ignore these options, so
 they have nothing to warn about - see the platform notes below.)
 
+### URL tokens are redacted
+
+Some sign-in flows put the session in the page URL - `#access_token=…` and
+`refresh_token=…` after an OAuth or magic-link callback, `?token=…` or
+`?token_hash=…` in the link itself. The SDK replaces those values with
+`[redacted]` in every event before it leaves the app: every string in an
+event's properties is checked (the page URL, the referrer, the first URL
+stored on a person, your own properties), for the parameter names
+`access_token`, `refresh_token`, `token_hash` and `token`, and for anything
+shaped like a JWT. The parameter name stays, so you can still see which page
+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.
+
 ### Consent gate
 
 Set `optOutCapturingByDefault: true` to capture nothing until your visitor
@@ -120,6 +134,24 @@ localhost limit does not: a native event has no page host, so there is
 nothing to tell a simulator from a phone. Server events are not counted at
 all - each one is a call your own code made.
 
+## React Native screen views
+
+On Expo Router, `<HeyCatchProvider>` records a screen view each time the
+route changes, named by the path (`/settings`, `/recipe/42`). The route's
+search params ride along as properties, minus anything that could identify
+a person or unlock an account: the `#` fragment, keys such as `email`,
+`code`, `token`, `password`, `passcode`, `secret`, `session`, `otp`,
+`pin`, `auth…` and anything containing `key`, plus any value that looks
+like an email address. Attribution params such as
+`utm_*` and ids are kept.
+
+If your app already records screens itself with `analytics.trackScreen`,
+turn the automatic ones off so each screen is not counted twice:
+
+```tsx
+<HeyCatchProvider trackScreens={false}>{children}</HeyCatchProvider>
+```
+
 ## License
 
 MIT