rsclick-log-sdk-web 0.2.0 → 0.2.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/README.md +134 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -8,6 +8,7 @@
|
|
|
8
8
|
- 自动维护 30 分钟 `session_id`
|
|
9
9
|
- 调用后端 `POST /track/collect` 上报事件
|
|
10
10
|
- 默认初始化后自动发送 `$page_view`
|
|
11
|
+
- 可选开启全局错误捕获并自动发送 `$error`
|
|
11
12
|
- 支持 SPA 场景下的路由切换自动发送 `$page_view`
|
|
12
13
|
- 登录态识别仅影响后续事件
|
|
13
14
|
|
|
@@ -59,6 +60,7 @@ await init({
|
|
|
59
60
|
- 初始化完成后自动发送当前页面的 `$page_view`
|
|
60
61
|
- 在 SPA 中监听 `history.pushState`、`history.replaceState`、`popstate`、`hashchange`
|
|
61
62
|
- 同一 URL 不会重复自动上报
|
|
63
|
+
- 默认不会自动捕获全局错误，如需开启请显式设置 `autoErrorCapture: true`
|
|
62
64
|
```
|
|
63
65
|
|
|
64
66
|
关闭默认 `$page_view`：
|
|
@@ -73,6 +75,26 @@ await init({
|
|
|
73
75
|
});
|
|
74
76
|
```
|
|
75
77
|
|
|
78
|
+
开启全局错误自动采集：
|
|
79
|
+
|
|
80
|
+
```ts
|
|
81
|
+
import { init } from "rsclick-log-sdk-web";
|
|
82
|
+
|
|
83
|
+
await init({
|
|
84
|
+
writeKey: "trk_live_xxx",
|
|
85
|
+
endpoint: "https://your-api.example.com/track/collect",
|
|
86
|
+
autoErrorCapture: true,
|
|
87
|
+
});
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
开启后 SDK 会在浏览器层监听：
|
|
91
|
+
|
|
92
|
+
- `window.error`
|
|
93
|
+
- `window.unhandledrejection`
|
|
94
|
+
|
|
95
|
+
这套机制对 `Vue`、`React`、`SolidJS`、`Next.js` 都可用，因为依赖的是浏览器全局事件而不是框架私有 API。
|
|
96
|
+
如果你在框架内还使用了 `ErrorBoundary`、`onErrorCaptured` 等机制，仍然可以继续手动调用 `track("$error")` 补充业务上下文。
|
|
97
|
+
|
|
76
98
|
## 事件示例
|
|
77
99
|
|
|
78
100
|
```ts
|
|
@@ -86,6 +108,24 @@ await track("click_signup_button", {
|
|
|
86
108
|
});
|
|
87
109
|
```
|
|
88
110
|
|
|
111
|
+
手动捕获错误并补充框架上下文：
|
|
112
|
+
|
|
113
|
+
```ts
|
|
114
|
+
import { captureError } from "rsclick-log-sdk-web";
|
|
115
|
+
|
|
116
|
+
try {
|
|
117
|
+
throw new Error("checkout failed");
|
|
118
|
+
} catch (error) {
|
|
119
|
+
await captureError(error, {
|
|
120
|
+
source: "manual_try_catch",
|
|
121
|
+
properties: {
|
|
122
|
+
component: "CheckoutPage",
|
|
123
|
+
action: "submit_order",
|
|
124
|
+
},
|
|
125
|
+
});
|
|
126
|
+
}
|
|
127
|
+
```
|
|
128
|
+
|
|
89
129
|
主动发送页面浏览事件：
|
|
90
130
|
|
|
91
131
|
```ts
|
|
@@ -153,6 +193,100 @@ SDK 默认上报以下字段：
|
|
|
153
193
|
1. 统一使用 `fetch(..., { mode: "cors", credentials: "omit", keepalive: true })`
|
|
154
194
|
2. SDK 不再依赖 `navigator.sendBeacon`
|
|
155
195
|
|
|
196
|
+
当开启 `autoErrorCapture` 时，`$error` 事件默认会带上以下属性中的可用字段：
|
|
197
|
+
|
|
198
|
+
- `error_kind`：`window_error` 或 `unhandledrejection`
|
|
199
|
+
- `message`
|
|
200
|
+
- `error_name`
|
|
201
|
+
- `filename`
|
|
202
|
+
- `lineno`
|
|
203
|
+
- `colno`
|
|
204
|
+
- `stack`
|
|
205
|
+
|
|
206
|
+
手动调用 `captureError()` 时，还会额外带上：
|
|
207
|
+
|
|
208
|
+
- `error_kind`：固定为 `captured_error`
|
|
209
|
+
- `source`：手动传入的来源标识，默认值为 `manual`
|
|
210
|
+
|
|
211
|
+
## 框架接入示例
|
|
212
|
+
|
|
213
|
+
React Error Boundary：
|
|
214
|
+
|
|
215
|
+
```tsx
|
|
216
|
+
import { captureError } from "rsclick-log-sdk-web";
|
|
217
|
+
|
|
218
|
+
export const AppErrorFallback = ({ error }: { error: Error }) => {
|
|
219
|
+
void captureError(error, {
|
|
220
|
+
source: "react_error_boundary",
|
|
221
|
+
properties: {
|
|
222
|
+
component: "AppErrorFallback",
|
|
223
|
+
},
|
|
224
|
+
});
|
|
225
|
+
|
|
226
|
+
return <div>Something went wrong.</div>;
|
|
227
|
+
};
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
Vue 3 `onErrorCaptured`：
|
|
231
|
+
|
|
232
|
+
```ts
|
|
233
|
+
import { onErrorCaptured } from "vue";
|
|
234
|
+
import { captureError } from "rsclick-log-sdk-web";
|
|
235
|
+
|
|
236
|
+
onErrorCaptured((error, instance, info) => {
|
|
237
|
+
void captureError(error, {
|
|
238
|
+
source: "vue_on_error_captured",
|
|
239
|
+
properties: {
|
|
240
|
+
component: instance?.type?.name ?? null,
|
|
241
|
+
info,
|
|
242
|
+
},
|
|
243
|
+
});
|
|
244
|
+
|
|
245
|
+
return false;
|
|
246
|
+
});
|
|
247
|
+
```
|
|
248
|
+
|
|
249
|
+
SolidJS `ErrorBoundary`：
|
|
250
|
+
|
|
251
|
+
```tsx
|
|
252
|
+
import { ErrorBoundary } from "solid-js";
|
|
253
|
+
import { captureError } from "rsclick-log-sdk-web";
|
|
254
|
+
|
|
255
|
+
<ErrorBoundary
|
|
256
|
+
fallback={(error) => {
|
|
257
|
+
void captureError(error, {
|
|
258
|
+
source: "solid_error_boundary",
|
|
259
|
+
});
|
|
260
|
+
|
|
261
|
+
return <div>Something went wrong.</div>;
|
|
262
|
+
}}
|
|
263
|
+
>
|
|
264
|
+
<App />
|
|
265
|
+
</ErrorBoundary>;
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
Next.js `app/error.tsx`：
|
|
269
|
+
|
|
270
|
+
```tsx
|
|
271
|
+
"use client";
|
|
272
|
+
|
|
273
|
+
import { useEffect } from "react";
|
|
274
|
+
import { captureError } from "rsclick-log-sdk-web";
|
|
275
|
+
|
|
276
|
+
export default function GlobalError({ error }: { error: Error & { digest?: string } }) {
|
|
277
|
+
useEffect(() => {
|
|
278
|
+
void captureError(error, {
|
|
279
|
+
source: "next_app_error",
|
|
280
|
+
properties: {
|
|
281
|
+
digest: error.digest ?? null,
|
|
282
|
+
},
|
|
283
|
+
});
|
|
284
|
+
}, [error]);
|
|
285
|
+
|
|
286
|
+
return <html><body>Something went wrong.</body></html>;
|
|
287
|
+
}
|
|
288
|
+
```
|
|
289
|
+
|
|
156
290
|
## 发布说明
|
|
157
291
|
|
|
158
292
|
当前 npm 包名为 `rsclick-log-sdk-web`。如果要发布到 npm，按下面步骤操作：
|