@starko-one/sdk 0.0.0-stage → 0.1.0-beta.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +248 -0
- package/LICENSE +17 -0
- package/NOTICE +58 -0
- package/README.md +81 -2
- package/dist/api-BAFm4Lxj.d.ts +558 -0
- package/dist/api-DNrctwJu.d.cts +558 -0
- package/dist/browser/index.cjs +168 -0
- package/dist/browser/index.d.cts +131 -0
- package/dist/browser/index.d.ts +131 -0
- package/dist/browser/index.js +7 -0
- package/dist/build/rollup.cjs +22 -0
- package/dist/build/rollup.d.cts +34 -0
- package/dist/build/rollup.d.ts +34 -0
- package/dist/build/rollup.js +3 -0
- package/dist/build/vite.cjs +51 -0
- package/dist/build/vite.d.cts +23 -0
- package/dist/build/vite.d.ts +23 -0
- package/dist/build/vite.js +46 -0
- package/dist/build/webpack.cjs +18 -0
- package/dist/build/webpack.d.cts +39 -0
- package/dist/build/webpack.d.ts +39 -0
- package/dist/build/webpack.js +3 -0
- package/dist/chunk-2PM4FRM5.cjs +431 -0
- package/dist/chunk-335HNCOJ.js +249 -0
- package/dist/chunk-3AW5B2WW.js +115 -0
- package/dist/chunk-3R5TQAWD.js +216 -0
- package/dist/chunk-6H5MOPTQ.cjs +1230 -0
- package/dist/chunk-7TKNT3QJ.cjs +2487 -0
- package/dist/chunk-A4WLNFMU.cjs +220 -0
- package/dist/chunk-ALYFFOPR.cjs +134 -0
- package/dist/chunk-BVVFVRMO.js +1113 -0
- package/dist/chunk-CIHNKN62.cjs +15 -0
- package/dist/chunk-CMGCH6HD.js +1212 -0
- package/dist/chunk-D6QAPQ7L.cjs +56 -0
- package/dist/chunk-DUO5V6WZ.js +213 -0
- package/dist/chunk-EC2WZ6PG.js +90 -0
- package/dist/chunk-EFURLFJT.cjs +187 -0
- package/dist/chunk-EROUORMY.js +53 -0
- package/dist/chunk-LXBXFOAP.cjs +96 -0
- package/dist/chunk-MF6SA6DB.js +563 -0
- package/dist/chunk-N5R6ORIB.js +413 -0
- package/dist/chunk-N6R6BWHK.cjs +142 -0
- package/dist/chunk-QAGGN2T7.cjs +225 -0
- package/dist/chunk-QV4HRIDD.cjs +659 -0
- package/dist/chunk-TKNDYQB3.cjs +583 -0
- package/dist/chunk-UI5YC4TH.js +131 -0
- package/dist/chunk-VEHZYLK6.cjs +1151 -0
- package/dist/chunk-VNCWOGTI.js +12 -0
- package/dist/chunk-VWNIOGE6.js +180 -0
- package/dist/chunk-WDKRKGYF.js +608 -0
- package/dist/chunk-XOZIXBUK.js +2462 -0
- package/dist/chunk-ZS3K3SDR.cjs +258 -0
- package/dist/cli/index.cjs +2780 -0
- package/dist/common-DLFAqL2d.d.cts +36 -0
- package/dist/common-DbSXkaw6.d.ts +36 -0
- package/dist/dedupe-Bh5riD8Z.d.cts +13 -0
- package/dist/dedupe-DoYiSx-9.d.ts +13 -0
- package/dist/handler-BcnsnvhF.d.cts +82 -0
- package/dist/handler-qHzilC9T.d.ts +82 -0
- package/dist/index.cjs +309 -0
- package/dist/index.d.cts +187 -0
- package/dist/index.d.ts +187 -0
- package/dist/index.js +4 -0
- package/dist/next/client.cjs +113 -0
- package/dist/next/client.d.cts +26 -0
- package/dist/next/client.d.ts +26 -0
- package/dist/next/client.js +41 -0
- package/dist/next/config.cjs +277 -0
- package/dist/next/config.d.cts +193 -0
- package/dist/next/config.d.ts +193 -0
- package/dist/next/config.js +263 -0
- package/dist/next/index.cjs +148 -0
- package/dist/next/index.d.cts +32 -0
- package/dist/next/index.d.ts +32 -0
- package/dist/next/index.js +59 -0
- package/dist/node/index.cjs +257 -0
- package/dist/node/index.d.cts +145 -0
- package/dist/node/index.d.ts +145 -0
- package/dist/node/index.js +83 -0
- package/dist/options-BUhWuWJX.d.cts +79 -0
- package/dist/options-BUhWuWJX.d.ts +79 -0
- package/dist/react/index.cjs +107 -0
- package/dist/react/index.d.cts +84 -0
- package/dist/react/index.d.ts +84 -0
- package/dist/react/index.js +103 -0
- package/dist/scope-D1ouJm2h.d.cts +628 -0
- package/dist/scope-D1ouJm2h.d.ts +628 -0
- package/dist/server-edge-7624N3WF.cjs +51 -0
- package/dist/server-edge-BEEXWL7T.js +48 -0
- package/dist/server-node-ET4LIPEC.cjs +27 -0
- package/dist/server-node-TQUVMZUC.js +24 -0
- package/dist/session-C_WzbEN2.d.cts +4 -0
- package/dist/session-C_WzbEN2.d.ts +4 -0
- package/dist/session-propagation-Pr0Zb9Zn.d.cts +30 -0
- package/dist/session-propagation-RM5py1bp.d.ts +30 -0
- package/dist/starko.min.js +6 -0
- package/docs/browser.md +386 -0
- package/docs/configuration.md +310 -0
- package/docs/nextjs.md +488 -0
- package/docs/node.md +427 -0
- package/docs/other-backends.md +232 -0
- package/docs/privacy.md +112 -0
- package/docs/react.md +187 -0
- package/docs/source-maps.md +482 -0
- package/docs/troubleshooting.md +263 -0
- package/docs/widget.md +84 -0
- package/docs/wire-format.md +547 -0
- package/package.json +191 -4
package/docs/browser.md
ADDED
|
@@ -0,0 +1,386 @@
|
|
|
1
|
+
# Browser
|
|
2
|
+
|
|
3
|
+
Error tracking for any web page, with or without a framework. For React see
|
|
4
|
+
also [react.md](./react.md); for Next.js use [nextjs.md](./nextjs.md) instead
|
|
5
|
+
of this page.
|
|
6
|
+
|
|
7
|
+
## Install with npm
|
|
8
|
+
|
|
9
|
+
```sh
|
|
10
|
+
npm install @starko-one/sdk
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
```ts
|
|
14
|
+
import * as Starko from "@starko-one/sdk/browser";
|
|
15
|
+
|
|
16
|
+
Starko.init({
|
|
17
|
+
workspaceKey: "<STARKO_WORKSPACE_KEY>",
|
|
18
|
+
release: "shop@4.12.0",
|
|
19
|
+
environment: "production",
|
|
20
|
+
});
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
Set `environment` per deployment. If your build tool sets it from
|
|
24
|
+
`NODE_ENV`, mind that hosts with preview deployments build those in
|
|
25
|
+
production mode too: use the host's own variable where it has one (see
|
|
26
|
+
[nextjs.md](./nextjs.md#environment-production-or-preview)).
|
|
27
|
+
|
|
28
|
+
Call `init` once, in your entry file, before the rest of your app runs:
|
|
29
|
+
errors thrown before `init` are not captured. Calling `init` again replaces
|
|
30
|
+
the previous client. `init` never throws; it returns the client, or
|
|
31
|
+
`undefined` when it could not start.
|
|
32
|
+
|
|
33
|
+
The workspace key is the workspace id shown in Starko under Settings. It is
|
|
34
|
+
public: it only lets a page send errors. Never put a secret key
|
|
35
|
+
(`sk_starko_…`) in browser code.
|
|
36
|
+
|
|
37
|
+
Use as `release` the release your source maps were uploaded for. If you
|
|
38
|
+
use one of the build plugins, you can leave it out: the plugin writes the
|
|
39
|
+
release it uploaded for into your bundles and `init` uses it (it is read
|
|
40
|
+
for each event, so `init` may run before those bundles load). See
|
|
41
|
+
[source-maps.md](./source-maps.md).
|
|
42
|
+
|
|
43
|
+
## Install with a script tag
|
|
44
|
+
|
|
45
|
+
```html
|
|
46
|
+
<script
|
|
47
|
+
src="https://cdn.jsdelivr.net/npm/@starko-one/sdk@0.1.0-beta.1/dist/starko.min.js"
|
|
48
|
+
data-workspace-key="<STARKO_WORKSPACE_KEY>"
|
|
49
|
+
data-release="shop@4.12.0"
|
|
50
|
+
data-environment="production"
|
|
51
|
+
></script>
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Always pin the exact version in the URL. An unpinned URL changes under you
|
|
55
|
+
when a new version is published. The bundle is 53 kB minified, 19.04 kB
|
|
56
|
+
gzipped.
|
|
57
|
+
|
|
58
|
+
The tag works as a classic script, with `defer` or `async`, and as
|
|
59
|
+
`<script type="module">`; in a module the bundle finds its tag by the
|
|
60
|
+
`data-workspace-key` attribute. A classic script defines `window.Starko`;
|
|
61
|
+
a module sets it unless the page already has a `Starko` global. With
|
|
62
|
+
`defer`, `async` or `type="module"`, the bundle runs after inline scripts
|
|
63
|
+
that follow the tag, so start it with the attributes, or call `init` from a
|
|
64
|
+
script of the same kind placed after the tag (`defer` and module scripts
|
|
65
|
+
run in document order; `async` ones do not).
|
|
66
|
+
|
|
67
|
+
With `data-workspace-key` on the tag, the bundle starts itself. The other
|
|
68
|
+
attributes it reads:
|
|
69
|
+
|
|
70
|
+
| Attribute | Option |
|
|
71
|
+
| --- | --- |
|
|
72
|
+
| `data-workspace-key` | `workspaceKey`. Without it the bundle does not start; call `Starko.init` yourself. |
|
|
73
|
+
| `data-release` | `release` |
|
|
74
|
+
| `data-environment` | `environment` |
|
|
75
|
+
| `data-host` | `host` (default `https://v2.starko.one`) |
|
|
76
|
+
| `data-debug` | `debug: true` when the attribute is present |
|
|
77
|
+
|
|
78
|
+
For any other option, leave `data-workspace-key` off and call `init` from your
|
|
79
|
+
own script after the tag:
|
|
80
|
+
|
|
81
|
+
```html
|
|
82
|
+
<script src="https://cdn.jsdelivr.net/npm/@starko-one/sdk@0.1.0-beta.1/dist/starko.min.js"></script>
|
|
83
|
+
<script>
|
|
84
|
+
window.Starko.init({
|
|
85
|
+
workspaceKey: "<STARKO_WORKSPACE_KEY>",
|
|
86
|
+
release: "shop@4.12.0",
|
|
87
|
+
sampleRate: 0.5,
|
|
88
|
+
});
|
|
89
|
+
</script>
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
The bundle exposes `window.Starko` with `init`, `captureException`,
|
|
93
|
+
`captureMessage`, `setUser`, `identify`, `setTag`, `setTags`, `setExtra`,
|
|
94
|
+
`setExtras`, `setContext`, `addBreadcrumb`, `withScope`, `flush`, `close`,
|
|
95
|
+
`getClient`, `SDK_VERSION` and `consoleErrorCaptureIntegration`. The other
|
|
96
|
+
integration factories are only in the npm package. Errors raised entirely
|
|
97
|
+
inside the bundle itself are never reported.
|
|
98
|
+
|
|
99
|
+
## Identify the user
|
|
100
|
+
|
|
101
|
+
An error is linked to a customer in Starko only when the link is verified.
|
|
102
|
+
Send the user with a **user hash**: an HMAC-SHA256, in hex, of the user's id
|
|
103
|
+
(or of their email when you have no id), computed on **your backend** with
|
|
104
|
+
your workspace's identity secret. It is the same hash the Starko widget's
|
|
105
|
+
`identify` takes.
|
|
106
|
+
|
|
107
|
+
On your server (Node shown; any language with HMAC-SHA256 works):
|
|
108
|
+
|
|
109
|
+
```js
|
|
110
|
+
import { createHmac } from "node:crypto";
|
|
111
|
+
|
|
112
|
+
// Never run this in the browser: the identity secret must stay on your server.
|
|
113
|
+
// STARKO_IDENTITY_SECRET is an environment variable of your own holding it.
|
|
114
|
+
export function starkoUserHash(userId) {
|
|
115
|
+
return createHmac("sha256", process.env.STARKO_IDENTITY_SECRET).update(userId).digest("hex");
|
|
116
|
+
}
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
Hand the hash to the page with the signed-in user (in your session payload,
|
|
120
|
+
say), then:
|
|
121
|
+
|
|
122
|
+
```ts
|
|
123
|
+
import * as Starko from "@starko-one/sdk/browser";
|
|
124
|
+
|
|
125
|
+
export function onSignIn(user: { id: string; email: string; name: string }, starkoUserHash: string) {
|
|
126
|
+
Starko.identify({ id: user.id, email: user.email, name: user.name }, starkoUserHash);
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
export function onSignOut() {
|
|
130
|
+
Starko.setUser(null);
|
|
131
|
+
}
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
- `identify(user, userHash)` sets the user and the hash. `identify("user_123", hash)` takes the id alone.
|
|
135
|
+
- `setUser({ id, email, name })` sets a user without a hash.
|
|
136
|
+
- `init({ user, userHash })` sets them at start.
|
|
137
|
+
- A user without a valid hash is kept on the error as text (the id and email
|
|
138
|
+
you sent) and is never linked to a customer, never counted as an affected
|
|
139
|
+
customer and never attached to a ticket: anyone can put any id in a
|
|
140
|
+
browser request, so an unverified id cannot be trusted.
|
|
141
|
+
- When the Starko widget is on the page, the SDK also sends the widget's own
|
|
142
|
+
token, which links the error to the widget's customer without a hash.
|
|
143
|
+
The token is checked first. When the widget's customer was identified
|
|
144
|
+
without verification (an email typed into the widget, for example), the
|
|
145
|
+
error is still linked to them and Starko labels the link "unverified"; a
|
|
146
|
+
valid hash you sent with `identify` links your user as verified instead.
|
|
147
|
+
See [widget.md](./widget.md).
|
|
148
|
+
- The hash is a credential. The SDK never logs it and the server does not store it.
|
|
149
|
+
|
|
150
|
+
## Capture errors yourself
|
|
151
|
+
|
|
152
|
+
```ts
|
|
153
|
+
import * as Starko from "@starko-one/sdk/browser";
|
|
154
|
+
|
|
155
|
+
async function checkout(cartId: string) {
|
|
156
|
+
try {
|
|
157
|
+
await fetch(`/api/checkout/${cartId}`, { method: "POST" });
|
|
158
|
+
} catch (error) {
|
|
159
|
+
const eventId = Starko.captureException(error, {
|
|
160
|
+
tags: { area: "checkout" },
|
|
161
|
+
extra: { cartId },
|
|
162
|
+
});
|
|
163
|
+
console.log("reported as", eventId);
|
|
164
|
+
}
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
Starko.captureMessage("Payment provider fell back to redirect flow", "warning");
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
- `captureException(value, hint?)` takes anything thrown (an `Error`, a
|
|
171
|
+
string, an object) and returns the event id (`""` before `init`). The hint
|
|
172
|
+
may set `tags`, `extra`, `contexts`, `fingerprint` (events with the same
|
|
173
|
+
fingerprint become one issue) and `level`. Captured errors are recorded as
|
|
174
|
+
handled.
|
|
175
|
+
- `captureMessage(message, level?)` reports a message with the caller's
|
|
176
|
+
stack. The level defaults to `"info"`. Only `error` and `fatal` events can
|
|
177
|
+
file a ticket.
|
|
178
|
+
- The same error object is reported once, even if it is captured again or
|
|
179
|
+
later reaches the global handler.
|
|
180
|
+
|
|
181
|
+
Data for every later event:
|
|
182
|
+
|
|
183
|
+
```ts
|
|
184
|
+
import * as Starko from "@starko-one/sdk/browser";
|
|
185
|
+
|
|
186
|
+
Starko.setTag("plan", "pro");
|
|
187
|
+
Starko.setTags({ region: "eu", tenant: "acme" });
|
|
188
|
+
Starko.setExtra("featureFlags", { newCheckout: true });
|
|
189
|
+
Starko.setContext("cart", { items: 3, currency: "EUR" });
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
Data for one capture only:
|
|
193
|
+
|
|
194
|
+
```ts
|
|
195
|
+
import * as Starko from "@starko-one/sdk/browser";
|
|
196
|
+
|
|
197
|
+
function reportImportFailure(error: unknown, fileName: string) {
|
|
198
|
+
Starko.withScope((scope) => {
|
|
199
|
+
scope.setTag("feature", "import");
|
|
200
|
+
scope.setExtra("fileName", fileName);
|
|
201
|
+
Starko.captureException(error);
|
|
202
|
+
});
|
|
203
|
+
}
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
## Breadcrumbs
|
|
207
|
+
|
|
208
|
+
Breadcrumbs are what happened before the error. Recorded automatically:
|
|
209
|
+
|
|
210
|
+
| Kind | What is recorded |
|
|
211
|
+
| --- | --- |
|
|
212
|
+
| Clicks | A short CSS-like path of the element (`form#login > button.primary`), never its text or an input's value. Nothing inside elements with `starko-mask` / `starko-no-capture` classes or `data-starko-mask` / `data-starko-no-capture` attributes. |
|
|
213
|
+
| Navigation | `pushState`, `replaceState` and back/forward: from and to (path only when same-origin). |
|
|
214
|
+
| `fetch` and XHR | Method, URL and status code. Never bodies, cookies or headers. Requests to Starko are not recorded. |
|
|
215
|
+
| Console | `console.warn` and `console.error` only, as text cut to 200 characters. |
|
|
216
|
+
|
|
217
|
+
At most 50 breadcrumbs are kept (`maxBreadcrumbs`), and at most 32 KiB of
|
|
218
|
+
them are sent with an event.
|
|
219
|
+
|
|
220
|
+
Add your own, edit or drop any of them:
|
|
221
|
+
|
|
222
|
+
```ts
|
|
223
|
+
import * as Starko from "@starko-one/sdk/browser";
|
|
224
|
+
|
|
225
|
+
Starko.init({
|
|
226
|
+
workspaceKey: "<STARKO_WORKSPACE_KEY>",
|
|
227
|
+
beforeBreadcrumb(breadcrumb) {
|
|
228
|
+
if (breadcrumb.category === "console" && breadcrumb.message?.includes("[analytics]")) return null;
|
|
229
|
+
return breadcrumb;
|
|
230
|
+
},
|
|
231
|
+
});
|
|
232
|
+
|
|
233
|
+
Starko.addBreadcrumb({ category: "cart", message: "Coupon applied", data: { code: "SPRING" } });
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
To turn off one kind, replace the default `Breadcrumbs` integration (an
|
|
237
|
+
integration with the same name as a default replaces it):
|
|
238
|
+
|
|
239
|
+
```ts
|
|
240
|
+
import * as Starko from "@starko-one/sdk/browser";
|
|
241
|
+
import { breadcrumbsIntegration } from "@starko-one/sdk/browser";
|
|
242
|
+
|
|
243
|
+
Starko.init({
|
|
244
|
+
workspaceKey: "<STARKO_WORKSPACE_KEY>",
|
|
245
|
+
integrations: [breadcrumbsIntegration({ console: false, dom: true, fetch: true, xhr: true, history: true })],
|
|
246
|
+
});
|
|
247
|
+
```
|
|
248
|
+
|
|
249
|
+
## `beforeSend`
|
|
250
|
+
|
|
251
|
+
The last step before an event is queued. Return the event (changed or not),
|
|
252
|
+
or `null` to drop it. It may be `async`.
|
|
253
|
+
|
|
254
|
+
```ts
|
|
255
|
+
import * as Starko from "@starko-one/sdk/browser";
|
|
256
|
+
|
|
257
|
+
Starko.init({
|
|
258
|
+
workspaceKey: "<STARKO_WORKSPACE_KEY>",
|
|
259
|
+
beforeSend(event) {
|
|
260
|
+
if (event.request?.url?.includes("/admin/")) return null;
|
|
261
|
+
if (event.user) delete event.user.email;
|
|
262
|
+
return event;
|
|
263
|
+
},
|
|
264
|
+
});
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
- It runs after filtering, sampling and the rate limits, so it is not called
|
|
268
|
+
for events that would be dropped anyway.
|
|
269
|
+
- If it throws, the event is dropped (it may have been the step that removes
|
|
270
|
+
personal data). An async `beforeSend` that has not settled after
|
|
271
|
+
`beforeSendTimeoutMs` (default 5000 ms) is abandoned and its event dropped.
|
|
272
|
+
- The URL redaction described in [privacy.md](./privacy.md) runs after
|
|
273
|
+
`beforeSend`, so the event you see still has the raw URLs.
|
|
274
|
+
|
|
275
|
+
## Filter noise
|
|
276
|
+
|
|
277
|
+
Dropped before anything is sent, with no setting needed:
|
|
278
|
+
|
|
279
|
+
- an error with no message and no stack;
|
|
280
|
+
- a cross-origin `Script error.` without a stack (an error in a script from
|
|
281
|
+
another origin loaded without `crossorigin`; the browser hides its details);
|
|
282
|
+
- an error with a browser extension in its top three frames;
|
|
283
|
+
- `ResizeObserver loop …` errors;
|
|
284
|
+
- aborted requests (`AbortError`, "The operation was aborted", …);
|
|
285
|
+
- plain network failures (`Failed to fetch`, `Load failed`, `NetworkError …`
|
|
286
|
+
without a stack);
|
|
287
|
+
- errors raised entirely inside Starko's own scripts (widget, recorder, this SDK);
|
|
288
|
+
- the same error twice in a row (same type, message, frames, fingerprint,
|
|
289
|
+
user and session).
|
|
290
|
+
|
|
291
|
+
Your own rules:
|
|
292
|
+
|
|
293
|
+
```ts
|
|
294
|
+
import * as Starko from "@starko-one/sdk/browser";
|
|
295
|
+
|
|
296
|
+
Starko.init({
|
|
297
|
+
workspaceKey: "<STARKO_WORKSPACE_KEY>",
|
|
298
|
+
ignoreErrors: ["Non-critical widget timeout", /^ChunkLoadError/],
|
|
299
|
+
allowUrls: [/^https:\/\/shop\.example\.com\//],
|
|
300
|
+
denyUrls: [/\/vendor\/legacy-chat\.js/],
|
|
301
|
+
});
|
|
302
|
+
```
|
|
303
|
+
|
|
304
|
+
- `ignoreErrors` matches `Type: message` and `message`: a string matches
|
|
305
|
+
anywhere in it, a `RegExp` is tested against it.
|
|
306
|
+
- `allowUrls` / `denyUrls` match the file of the most recent stack frame that
|
|
307
|
+
has a file. An event without such a frame passes both.
|
|
308
|
+
- Rules set for the workspace in Starko (the remote config, below) drop
|
|
309
|
+
matching events too.
|
|
310
|
+
|
|
311
|
+
The built-in filters are the `InboundFilters` integration; removing it (see
|
|
312
|
+
[configuration.md](./configuration.md#adding-and-removing-integrations))
|
|
313
|
+
turns all of them off.
|
|
314
|
+
|
|
315
|
+
## Sampling and limits
|
|
316
|
+
|
|
317
|
+
```ts
|
|
318
|
+
import * as Starko from "@starko-one/sdk/browser";
|
|
319
|
+
|
|
320
|
+
Starko.init({ workspaceKey: "<STARKO_WORKSPACE_KEY>", sampleRate: 0.25 });
|
|
321
|
+
```
|
|
322
|
+
|
|
323
|
+
`sampleRate` (0 to 1, default 1) is the share of events sent. The workspace's
|
|
324
|
+
remote sample rate multiplies it. Limits that always apply in a browser:
|
|
325
|
+
|
|
326
|
+
- per error: 10 at once, then 1 every 10 seconds. An error here is its
|
|
327
|
+
type and the first 120 characters of its message, with numbers, UUIDs
|
|
328
|
+
and long hex ids masked (`Order 1234 not found` and `Order 98 not found`
|
|
329
|
+
count as one); without a message, its type and the file and line it was
|
|
330
|
+
thrown from;
|
|
331
|
+
- 100 events per page load (`maxEventsPerLifetime`);
|
|
332
|
+
- 100 events waiting in memory (`maxQueueSize`); the oldest are dropped first.
|
|
333
|
+
|
|
334
|
+
Drops by the first two limits are logged to the console even without
|
|
335
|
+
`debug`, at most once a minute per limit, with the number dropped since the
|
|
336
|
+
previous line; a full queue is logged once.
|
|
337
|
+
|
|
338
|
+
## Remote config
|
|
339
|
+
|
|
340
|
+
At `init` the SDK reads the workspace's settings from Starko
|
|
341
|
+
(`GET /api/v1/ingest/config`): whether error tracking is on, a sample rate
|
|
342
|
+
and suppression rules. Until the answer arrives (at most 10 seconds), up to
|
|
343
|
+
30 events are held; they are then sent or dropped by what it says. If error
|
|
344
|
+
tracking is off for the workspace, the SDK removes its hooks and sends
|
|
345
|
+
nothing. If the request fails, the SDK runs with the defaults (on, sample
|
|
346
|
+
rate 1, no rules).
|
|
347
|
+
|
|
348
|
+
`remoteConfig: false` skips the request; the workspace's on/off switch is
|
|
349
|
+
then only learned from the ingest API's answer to the first batch.
|
|
350
|
+
|
|
351
|
+
## Offline, and when the page is hidden
|
|
352
|
+
|
|
353
|
+
- Events are sent in batches of up to 20, one second after the first one
|
|
354
|
+
(`flushInterval`).
|
|
355
|
+
- A request that has not answered after 12 seconds (`requestTimeoutMs`) is
|
|
356
|
+
aborted and counts as a network failure.
|
|
357
|
+
- A failed batch is retried with back-off (waiting at least `Retry-After`
|
|
358
|
+
when the answer has one), at most three attempts. After
|
|
359
|
+
three batches in a row are given up, sending pauses for five minutes, and
|
|
360
|
+
resumes earlier when the browser fires `online`. Events captured while
|
|
361
|
+
offline wait in the queue (at most 100).
|
|
362
|
+
- When the page is hidden or unloaded (`visibilitychange` to hidden,
|
|
363
|
+
`pagehide`), the queue is sent at once with `keepalive`, so it can outlive
|
|
364
|
+
the page. Browsers allow 64 KiB of `keepalive` bodies in flight; a request
|
|
365
|
+
beyond that is sent without `keepalive` and may be cut off if the page is
|
|
366
|
+
really closing.
|
|
367
|
+
- Redirects are never followed. If your `host` redirects (`http://` to
|
|
368
|
+
`https://`, an apex domain), the batch is dropped and the console names the
|
|
369
|
+
redirect target, even without `debug`. Set `host` to the final address.
|
|
370
|
+
|
|
371
|
+
## Stop or flush
|
|
372
|
+
|
|
373
|
+
```ts
|
|
374
|
+
import * as Starko from "@starko-one/sdk/browser";
|
|
375
|
+
|
|
376
|
+
async function signOutEverywhere() {
|
|
377
|
+
await Starko.flush(2000); // true when everything queued went out within 2 s
|
|
378
|
+
await Starko.close(); // flush, then remove every hook; nothing is sent afterwards
|
|
379
|
+
}
|
|
380
|
+
```
|
|
381
|
+
|
|
382
|
+
## See also
|
|
383
|
+
|
|
384
|
+
- [configuration.md](./configuration.md): every option and its default.
|
|
385
|
+
- [privacy.md](./privacy.md): what is collected and how to collect less.
|
|
386
|
+
- [troubleshooting.md](./troubleshooting.md).
|