@heycatch/sdk 0.7.1-dev.1459 → 0.8.0-dev.1460

package/README.md

@@ -87,6 +87,39 @@ busy page sends more requests than a quiet one. `flushIntervalMs: 250` is the
 middle ground - still batched, but a window short enough that a navigation
 rarely lands inside it.
 
+## Volume limits
+
+A tracking call inside a render loop or an effect can send thousands of
+events from one browser tab, and nothing about the app looks broken while it
+does. So the SDK bounds what one session can send. None of this needs
+configuring. The first three limits are the SDK's own, and each logs one
+`[HeyCatch] …` console warning the first time it applies on a page, so a
+runaway loop is visible where you are already looking:
+
+- **5,000 events per session.** Past that, the rest of the session is
+  dropped until a new one starts. Real sessions do not get near this - it is
+  a backstop for a loop, not a quota for a busy user.
+- **60 person-property updates a minute.** Call `setPersonProperties` when a
+  property changes, not on every render. Updates past the budget are dropped;
+  pageviews and other events in the same session still flow.
+- **localhost is throttled, not filtered out.** A session on `localhost`,
+  `127.0.0.1` or a private-network host sends its first 1,000 events like
+  any other, then 60 a minute. A dev server hot-reloading for an hour cannot
+  flood your dashboard, and your first local test still shows up on the
+  Install page. Only this throttle is limited to local hosts: a production
+  session meets the other three limits like any other, and a local session
+  that reaches the cap is cut off like any other.
+- **5 events a second, sustained** (browser only). Bursts of up to 50 pass;
+  a steady stream faster than that is dropped. This one applies from the
+  first event, on every host, and it belongs to the transport rather than
+  the SDK, so there is no `[HeyCatch]` warning for it: the transport logs
+  its own console error, under its own prefix, for each call it drops.
+
+The session cap and the person-property budget apply in React Native too. The
+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.
+
 ## License
 
 MIT