# Tuỳ chọn cấu hình SDK

> release, environment, lấy mẫu, bỏ qua lỗi, breadcrumb và tệp đính kèm tuỳ chọn, cách gửi và giới hạn hàng đợi.

Các tuỳ chọn cho `init` (trình duyệt, React, phần client của TanStack Start) và cho callback của `withBelvador` (Cloudflare Workers, phần máy chủ của TanStack Start). Mọi tuỳ chọn trừ `dsn` đều không bắt buộc. Giá trị không hợp lệ quay về mặc định thay vì ném lỗi.

## Tuỳ chọn chung

| Tuỳ chọn | Kiểu | Mặc định | Tác dụng |
|---|---|---|---|
| `dsn` | `string` | — (bắt buộc trên trình duyệt) | DSN của project. Trên Workers có thể lấy từ `BELVADOR_DSN`. |
| `release` | `string` | chưa đặt | Phiên bản ứng dụng (số build, mã commit). Dùng để phát hiện lỗi tái phát và khớp [source map](https://belvador.dev/vi/docs/source-maps). |
| `environment` | `string` | `"production"` | `production`, `staging`, `preview`… Hiện và lọc được trên issue. |
| `dist` | `string` | chưa đặt | Một biến thể build trong cùng release, nếu bạn phát hành nhiều biến thể. |
| `sampleRate` | `number` 0–1 | `1` | Tỉ lệ event lỗi được gửi. `0.25` gửi khoảng một phần tư. |
| `ignoreErrors` | `(string \| RegExp)[]` | `[]` | Lỗi cần bỏ. Chuỗi khớp một phần của message; RegExp được thử trên message. |
| `captureAborted` | `boolean` | `false` | Báo cả việc người dùng đã huỷ: `AbortError` (hoặc lỗi do nó gây ra), hay lỗi máy chủ ném ra sau khi client đã ngắt kết nối. Mặc định tắt vì đóng tab không phải lỗi. `TimeoutError` luôn được báo. Từ 0.2.0. |
| `tracePropagation` | `{ targets: (string \| RegExp)[], baggage?: boolean }` | tắt | Thêm header `traceparent` và `sentry-trace` vào request tới các URL này, để lỗi và lượt chạy job giữa các dịch vụ được liên kết. Xem [Liên kết lỗi qua nhiều tầng](https://belvador.dev/vi/docs/sdk/tracing). Từ 0.3.0. |
| `beforeSend` | `(event, hint) => event \| null` | chưa đặt | Sửa hoặc bỏ một event. Trả `null` để bỏ. Có thể trả về promise. |
| `beforeBreadcrumb` | `(crumb, hint) => crumb \| null` | chưa đặt | Sửa hoặc bỏ một breadcrumb. |
| `maxBreadcrumbs` | `number` 0–100 | `50` | Số breadcrumb gần nhất đi kèm event. |
| `attachments` | `boolean` | `false` | Cho phép gửi tệp đính kèm. Tắt nghĩa là tệp đính kèm bị bỏ ngay trong ứng dụng. |
| `privacyPolicy` | `privacyPolicy(json)` | chưa đặt | Áp cả luật quyền riêng tư của project ngay trong app, lấy từ **Sao chép dạng code** trên trang Quyền riêng tư. Node vẫn áp các luật này dù có đặt hay không. Xem [Bảo vệ dữ liệu](https://belvador.dev/vi/docs/privacy). Từ 0.6.0. |
| `preview` | `boolean` | `false` | In từng envelope đúng như sẽ gửi và không gửi gì. Trên máy chủ, `BELVADOR_PREVIEW=1` có tác dụng tương tự. Từ 0.6.0. |
| `debug` | `boolean` | `false` | Ghi các quyết định của SDK ra console. Nhớ tắt lại khi lên production. |
| `disabled` | `boolean` | `false` | Giữ SDK tắt, ví dụ khi chạy test. |

`beforeSend` và `beforeBreadcrumb` chạy **trước** bước lọc bắt buộc của Belvador, nên không thể thêm dữ liệu mà bộ lọc sẽ xoá. Nếu hook ném lỗi hoặc promise bị từ chối, event hoặc breadcrumb đó bị bỏ.

```ts
init({
  dsn: "https://<public-key>@ingest.belvador.dev/<project-id>",
  release: import.meta.env.VITE_APP_VERSION,
  environment: import.meta.env.MODE,
  sampleRate: 1,
  ignoreErrors: ["ResizeObserver loop completed with undelivered notifications"],
  beforeSend(event) {
    // Bỏ lỗi từ công cụ quản trị nội bộ.
    if (event.request?.url?.includes("/internal-admin/")) return null;
    return event;
  },
});
```

## Breadcrumb

Breadcrumb là các bước trước khi lỗi xảy ra. Breadcrumb tự động **tắt** trong SDK của Belvador: chúng ghi lại người dùng bấm gì và gọi URL nào, có thể chứa dữ liệu cá nhân. Chỉ bật những gì bạn cần.

**Trình duyệt** (`@belvador/browser`, `@belvador/react`, client của TanStack Start):

```ts
init({
  dsn: "https://<public-key>@ingest.belvador.dev/<project-id>",
  instrument: { console: true, dom: true, fetch: true, xhr: true, history: true },
});
```

**Workers** (callback của `withBelvador`): `instrument: { console: true, fetch: true }`.

Breadcrumb bạn tự thêm bằng `addBreadcrumb` luôn được ghi, không cần tuỳ chọn nào.

## Tuỳ chọn chỉ có trên trình duyệt

| Tuỳ chọn | Mặc định | Tác dụng |
|---|---|---|
| `instrument` | tắt hết | Breadcrumb tự động, xem ở trên. |
| `wrapBrowserApis` | `false` | Bọc timer, `requestAnimationFrame` và event listener để lỗi bên trong có thêm ngữ cảnh. |
| `allowUrls` | mọi URL | Chỉ báo lỗi có stack đến từ các URL script này (chuỗi hoặc RegExp). |
| `denyUrls` | không có | Bỏ qua lỗi từ các URL script này. URL của tiện ích trình duyệt luôn bị bỏ qua. |
| `captureViewTransitionSkips` | `false` | Báo cả View Transition mà trình duyệt cố ý bỏ qua (trang bị ẩn, transition khác bắt đầu, `skipTransition()`). Mặc định tắt vì trình duyệt đang làm đúng thiết kế. Từ 0.3.0. |
| `offline` | `false` | Giữ lỗi gửi hỏng vì mạng trong trình duyệt này (IndexedDB) và gửi khi có mạng lại hoặc ở lần tải trang sau. Xem [Offline và gửi bền](https://belvador.dev/vi/docs/sdk/offline). Từ 0.6.0. |

## Hành vi riêng của Workers

Callback của `withBelvador` trả về các tuỳ chọn như trên nhưng `dsn` không bắt buộc, thêm `instrument: { console, fetch }`. Giá trị không trả về sẽ lấy từ biến của Worker:

| Thiết lập | Lấy từ, theo thứ tự |
|---|---|
| DSN | `dsn` trong callback → `BELVADOR_DSN` |
| Release | `release` trong callback → `BELVADOR_RELEASE` → `CF_VERSION_METADATA.id` |
| Environment | `environment` trong callback → `BELVADOR_ENVIRONMENT` → `production` |
| Công tắc tắt | `disabled` trong callback → `BELVADOR_DISABLED` = `1` hoặc `true` |

## Belvador cố định

Những điều sau không đổi được, để SDK chỉ gửi lỗi và không bao giờ tự thêm dữ liệu cá nhân:

- dữ liệu cá nhân do SDK tự thêm (`sendDefaultPii`) luôn tắt;
- tracing, session replay, log và profiling tắt, dữ liệu của chúng bị bỏ;
- không tunnel, không Spotlight, không tích hợp mặc định ngoài những gì Belvador thiết lập;
- chuỗi bị cắt ở 8.192 ký tự.

## Cách gửi

| Quy tắc | Giá trị |
|---|---|
| Đang chờ gửi | tối đa 30 envelope, tổng 1 MiB (6 MiB khi có tệp đính kèm) |
| Một tệp đính kèm | tối đa 5 MiB |
| Một lần gửi | huỷ sau 10 giây |
| Lỗi mạng và `500`/`502`/`503`/`504` | tối đa 5 lần thử; mỗi lần chờ ngẫu nhiên, dưới 1, 2, 4, rồi 8 giây (full jitter, từ 0.6.0); luôn cùng envelope và cùng event id |
| `503` có `Retry-After` | chờ đúng như yêu cầu, tối đa 60 giây |
| `429` | theo header giới hạn tốc độ: event mới thuộc loại đó bị bỏ ngay trong ứng dụng cho tới khi hết giới hạn |
| `401` / `403` | khoá sai hoặc đã bị thu hồi: ngừng gửi trong suốt vòng đời của trang hoặc isolate Worker |
| Lưu trữ | chỉ trong bộ nhớ — không ghi gì xuống đĩa hay `localStorage`, trừ khi bạn bật [`offline`](https://belvador.dev/vi/docs/sdk/offline) (trình duyệt) hoặc dùng `@belvador/spool` (máy chủ) |

Khi trang đang đóng, SDK gửi bằng `keepalive` trong giới hạn của trình duyệt (tối đa 60.000 byte, 15 request cùng lúc). Event không vừa, hoặc còn chờ lúc trang đóng, sẽ bị mất — trừ khi `offline: true` giữ chúng cho lần tải sau.