# Chọn SDK phù hợp

> Bảng nền tảng được hỗ trợ, phiên bản, yêu cầu đi kèm và những gì SDK Belvador gửi hoặc không gửi.

Belvador có gói SDK riêng cho các môi trường JavaScript, và dùng được với SDK Sentry chính thức cho Node.js và Python. Chọn dòng khớp với nơi code của bạn chạy.

## Tôi cần gói nào?

| Ứng dụng của bạn | Cài | Hướng dẫn |
|---|---|---|
| Ứng dụng Lovable, hoặc mọi ứng dụng TanStack Start chạy trên Cloudflare Workers | `@belvador/tanstack-start` | [TanStack Start và Lovable](https://belvador.dev/vi/docs/sdk/tanstack-start) |
| React render trên trình duyệt (Vite, Create React App, các dạng SPA khác) | `@belvador/react` | [React 18 và React 19](https://belvador.dev/vi/docs/sdk/react) |
| JavaScript trình duyệt không dùng React | `@belvador/browser` | [JavaScript trên trình duyệt](https://belvador.dev/vi/docs/sdk/browser) |
| Cloudflare Worker không phải TanStack Start | `@belvador/cloudflare` | [Cloudflare Workers](https://belvador.dev/vi/docs/sdk/cloudflare) |
| Máy chủ Node.js | `@sentry/node` + DSN Belvador và hàm lọc dữ liệu | [Node.js](https://belvador.dev/vi/docs/sdk/node) |
| Python | `sentry-sdk` + DSN Belvador và hàm lọc dữ liệu | [Python](https://belvador.dev/vi/docs/sdk/python) |

Ứng dụng có phần trình duyệt **và** phần máy chủ cần nối cả hai phần. `@belvador/tanstack-start` lo cả hai cho TanStack Start. Với các stack khác, cài gói trình duyệt ở frontend và SDK máy chủ ở backend — cả hai dùng chung DSN của project được.

## Gói, phiên bản và yêu cầu

| Gói | Phiên bản | Chạy ở | Ứng dụng cần có | Cờ runtime |
|---|---|---|---|---|
| `@belvador/browser` | 0.6.1 | Trình duyệt | Không | Không |
| `@belvador/react` | 0.6.1 | Trình duyệt | `react` ^18.0.0 hoặc ^19.0.0 | Không |
| `@belvador/cloudflare` | 0.6.1 | Cloudflare Workers | Không | `nodejs_compat` |
| `@belvador/tanstack-start` | 0.6.1 | Trình duyệt + Cloudflare Workers | `react` ^18.0.0 hoặc ^19.0.0; `@tanstack/react-router` ^1.168.0; `@tanstack/react-start` ^1.168.0 | `nodejs_compat` |

- Các gói là ES module dành cho công cụ build (Vite, esbuild, Wrangler). Cài đúng phiên bản ghi ở trên — `npm install <gói>@0.6.1` — để mọi bản build đều chạy cùng một bộ code đã được rà soát.
- `nodejs_compat` là cờ tương thích của Cloudflare Workers; cờ này cho mỗi request một phạm vi riêng nên user, tag và ngữ cảnh không bao giờ lẫn giữa các request.
- Phiên bản **0.x**: API còn có thể đổi trước 1.0.

## SDK gửi những gì

| Dữ liệu | Gửi |
|---|---|
| Lỗi (exception, lỗi chưa bắt, lỗi gửi thủ công) | Có |
| Check-in của công việc (withMonitor, captureCheckIn, heartbeat — chỉ phía máy chủ) | Có |
| Breadcrumb tự động (console, click, fetch, XHR, điều hướng) | Chỉ khi bạn bật |
| Tệp đính kèm | Chỉ khi bạn bật |
| Header trace (traceparent, sentry-trace) tới API của bạn | Chỉ khi bạn bật |
| Tracing / hiệu năng | Không — bị bỏ ngay trong ứng dụng |
| Session replay | Không — bị bỏ ngay trong ứng dụng |
| Logs | Không — bị bỏ ngay trong ứng dụng |
| Profiling | Không — bị bỏ ngay trong ứng dụng |

Mọi thứ không phải lỗi bị bỏ ngay trong ứng dụng, trước khi gửi đi. Node của bạn cũng chỉ lưu event lỗi, tệp đính kèm và báo cáo gửi, bất kể SDK gửi gì.

## Những gì được bắt tự động

Chỉ cài gói thì chưa đủ: mỗi phần runtime báo những lỗi nó thấy được, sau khi bạn nối nó vào.

| Phần đã nối | Báo lỗi gì |
|---|---|
| `init()` trên trình duyệt | Lỗi chưa bắt và promise bị từ chối mà không ai xử lý |
| `ErrorBoundary` của React | Lỗi xảy ra khi render, kèm component stack |
| Root hook của React 19 | Lỗi mà React tự xử lý: chưa bắt, bị boundary bắt, tự phục hồi được |
| `defaultOnCatch` của TanStack Start | Lỗi được hiển thị bởi error boundary của route |
| Middleware của TanStack Start | Lỗi ném ra trong server function và server route, kèm stack phía máy chủ |
| `withBelvador` của Cloudflare | Lỗi ném ra trong handler `fetch`, `scheduled`, `queue`, `email` và `tail` |

**Không tự động báo:** lỗi mà code của bạn đã bắt và xử lý (gọi `captureException` nếu vẫn muốn gửi), redirect, `notFound()`, và lỗi hoặc response của TanStack Start có mã trạng thái dưới 500.

## Xây trên Sentry JavaScript SDK

Mỗi gói là một lớp mỏng bên trên Sentry JavaScript SDK mã nguồn mở (MIT), khoá ở phiên bản **10.76.2** sau khi rà soát. Belvador thêm quy tắc bảo vệ dữ liệu, chính sách chỉ gửi lỗi, giới hạn việc gửi và bước kiểm tra DSN riêng. Event chỉ đi tới DSN Belvador của bạn; không cần tài khoản Sentry, và Belvador không liên kết với Sentry.

Vì dùng cùng giao thức, các SDK Sentry khác cũng chạy được với DSN Belvador — xem [Chuyển từ Sentry](https://belvador.dev/vi/docs/sdk/migration). Belvador mới kiểm chứng các cách cài trong các bài này.

## Đọc tiếp

- [Tham chiếu API của SDK](https://belvador.dev/vi/docs/sdk/reference) — mọi hàm được export.
- [Tuỳ chọn cấu hình SDK](https://belvador.dev/vi/docs/sdk/configuration) — release, environment, lấy mẫu, breadcrumb, tệp đính kèm.
- [Bảo vệ dữ liệu](https://belvador.dev/vi/docs/privacy) — những gì bị xoá trước khi gửi.