# @embrace-io/web-sdk 中文文档

规范地址：https://npmcn.com/package/%40embrace-io/web-sdk/

版本：2\.33\.0
npm 元数据更新时间：2026-11-09T15:22:10.174Z
中文译文更新时间：2026-11-13T14:56:15.601Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40embrace-io/web-sdk
原文对照：https://npmcn.com/package/%40embrace-io/web-sdk/?lang=original
项目主页：https://github.com/embrace-io/embrace-web-sdk
源码仓库：https://github.com/embrace-io/embrace-web-sdk

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：4.5 MB，2044 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：14 个
- peer 依赖：react ^16\.8\.0 \|\| ^17\.0\.0 \|\| ^18\.0\.0 \|\| ^19\.0\.0
- 首次发布：2025-04-03T23:18:02.968Z
- 最新版本发布：2026-11-09T15:22:09.805Z
- 近 30 天下载量：42425（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：71（近 12 个月 31 个）

## 中文简介

拥抱 Web SDK

## 安装

```sh
npm install @embrace-io/web-sdk
```

也可以使用：`pnpm add @embrace-io/web-sdk`、`yarn add @embrace-io/web-sdk`、`bun add @embrace-io/web-sdk`

## README

[![Embrace](https://embrace.io/docs/images/embrace_logo_black-text_transparent-bg_400x200.svg)](https://embrace.io/?utm_source=github&utm_medium=logo)

[![codecov](https://codecov.io/gh/embrace-io/embrace-web-sdk/graph/badge.svg?token=88948NPGPI)](https://codecov.io/gh/embrace-io/embrace-web-sdk) ![GitHub Release Date](https://img.shields.io/github/release-date/embrace-io/embrace-web-sdk) ![GitHub commit activity](https://img.shields.io/github/commit-activity/t/embrace-io/embrace-web-sdk) [![Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-orange)](https://npmcn.com/package/%40embrace-io/web-sdk/LICENSE) ![GitHub top language](https://img.shields.io/github/languages/top/embrace-io/embrace-web-sdk) ![Build and tests status](https://github.com/embrace-io/embrace-web-sdk/actions/workflows/ci-nodejs.yml/badge.svg)

# 拥抱 Web SDK

## 关于

Embrace Web SDK 建立在顶端之上 [打开几何](https://opentelemetry.io/) 为网络获取性能数据 应用程序,通过无缝连接网络和后端遥测,使您的系统具有完整的存储可观察性 就是这样.

通过这个SDK录制的遥测可以被 Embrace 平台所消耗,用于 Embrace 客户,但它也可以是 非客户直接向任何OTel收集器出口所收集的数据,或 它们主办或由其他供应商主办。 实际上,这种SDK是一种替代使用 [OpenTeleometry JS SDK 互联网档案馆的存檔,存档日期2013-12-02](https://github.com/open-telemetry/opentelemetry-js) 直接用于想要杠杆的网络应用程序 openTeleometer 生态系统的可观察性, 但也想要所有高级的遥测捕捉器, Embrace 已知 为.

目前,仅支持斯潘斯和日志,但未来会增加其他信号.

更多文件和实例可见于我们 [网络文档](https://embrace.io/docs/web/getting-started/)

## 快速启动

### 安装软件包

无 :

```sh
npm install @embrace-io/web-sdk
```

线条 :

```sh
yarn add @embrace-io/web-sdk
```

> \[TIP\] 关于CDN安装,见 [包含 SDK 作为代码片段来自 CDN](https://npmcn.com/package/%40embrace-io/web-sdk/#readme-including-the-sdk-as-a-code-snippet-from-cdn)。 。 。 .

### 初始化 SDK

首先注册一个Embrace账户,方法是: [https://dash.embrace.io/ signup (英语)](https://dash.embrace.io/signup) (见 [在不拥抱的情况下使用](https://npmcn.com/package/%40embrace-io/web-sdk/#readme-using-without-embrace) 如果你想跳过这一步的话.

一旦您创建了 Embrace 网络应用程序, 您可以使用您的应用程序初始化 SDK 应用程序的应用程序版本。 在应用的生命周期中,应该尽早开始以下工作 捕获遥测 :

```typescript
import { initSDK } from '@embrace-io/web-sdk';

const result = initSDK({
  appID: 'YOUR_EMBRACE_APP_ID',
  appVersion: 'YOUR_APP_VERSION',
});

if (!!result) {
  console.log('Successfully initialized the Embrace SDK');
} else {
  console.log('Failed to initialize the Embrace SDK');
}
```

此时你应该能够重建你的应用 让Embrace开始收集遥测数据 数据应该开始到 一旦SDK报告至少1个已完成会话,就会出现在 Embrace Dashboard 中. 这可以通过发射触发 您的应用程序,然后通过关闭标签/窗口或简单地将其放入背景来结束会话.

> \[注\] 可能要几分钟后 头几会才会出现在你的"拥抱"仪表板上.

## 添加痕迹

除了我们的自动仪器提供的东西之外 你还可以为您想要追踪的操作 创造自己的周期. 对于最基本的用法,只要开始一个周期,并在完成一些操作后结束:

```typescript
import { trace } from '@embrace-io/web-sdk';

const span = trace.startSpan('span-name');

someAsyncOperation()
  .then(() => span.end())
  .catch(() => span.fail());
```

只能输出明确结束的跨度 。 属性和活动也可以添加到时间段 生前或后期。 我们的API 包了 OpenTeleometry 软件 `Tracer` 这样你就可以跟随 [这些实例](https://opentelemetry.io/docs/languages/js/instrumentation/#create-spans) 更详尽的用例.

> \[注\] 导出到 Embrace 时, 属性值必须是字符串, 即使 OTel 接口允许更宽 类型范围

## 添加日志

您可以向会话中添加基本上下文, 并释放出在会话时间表中可以看到的面包屑:

```typescript
import { session } from '@embrace-io/web-sdk';

session.addBreadcrumb('something happened');
```

完整的日志信息也可以被发布 。 请注意,与出出出面包屑不同的是,木头更重并可能 触发网络请求以导出数据:

```typescript
import { log } from '@embrace-io/web-sdk';

log.message('Loading not finished in time.', 'error', {
  attributes: {
    propertyA: 'valueA',
    propertyB: 'valueB',
  },
});
```

## 添加例外情况

SDK自动捕获未处理的例外.

如果需要登录一个已处理的例外,可以使用人工方式调用logException方法:

```typescript
import { log } from '@embrace-io/web-sdk';

try {
  // some operation...
} catch (e) {
  log.logException(e as Error, {
    handled: true,
    attributes: {
      propertyA: 'valueA',
      propertyB: 'valueB',
    },
  });
}
```

## 反应仪器

与反应有关的仪器记录如下: [反应.md](https://npmcn.com/package/%40embrace-io/web-sdk/REACT.md)。 。 。 .

## 丰富元数据

您可以添加自定义属性, 作为当前会话的一部分 :

```typescript
import { session } from '@embrace-io/web-sdk';

session.addProperty('my-custom-property', 'some value');
```

这些属性默认只包含在本会话中. 如果您想要添加在所有会话中发送的永久属性, 您可以配置寿命选项 :

```typescript
session.addProperty('my-custom-property', 'some value', {
  lifespan: 'permanent',
});
```

## 不断更新您的应用程序版本

拥抱使用 `appVersion` 您可以提供收集到的片段遥测,并允许您查看差异 释放,因此,当您发布新版本的应用程序时,您应当确保更新此值。 若为 用你的电话 `package.json` 来跟踪你的应用软件的版本 然后不断更新的方法 就是读一下 初始化 SDK 时值( 假设您的捆绑器提供了导入 json 文件的方法) :

```typescript
import * as packageInfo from '../<some-path>/package.json';

initSDK({
  appID: 'YOUR_EMBRACE_APP_ID',
  appVersion: packageInfo.version,
});
```

或者,如果您的应用程序版本是作为您的 CI/CD 进程的一部分生成的, 您可以使用我们的 CLI 工具来注入您的 应用程序版本在构建时输入您的捆绑 。 这个过程是 [上传源代码图](https://npmcn.com/package/%40embrace-io/web-sdk/#readme-upload-sourcemaps) 说明 见下文.

## 上传源代码图

要在 Embrace 中查看象征性的堆栈痕迹, 您必须首先上传您的捆绑和源图 文档。 您可以使用我们的 CLI 工具这样做, 如果您还没有安装的话, 您可以使用:

无 :

```sh
npm install --save-dev @embrace-io/web-cli
```

线条 :

```sh
yarn add -D @embrace-io/web-cli
```

您还需要一个 `Symbol Upload` API标志. 这个可以在你的拥抱仪表板上找到 改为 [设置 - > API 密码](https://dash.embrace.io/settings/organization/api)。 。 。 .

然后把CLI连接到你的构建过程中 并把它指向你所构建的JS文件所居住的路径 执行上传 :

```sh
npx embrace-web-cli upload -a "YOUR_EMBRACE_APP_ID" -t "YOUR_EMBRACE_UPLOAD_API_TOKEN" -p "JS_BUILD_PATH"
```

> \[尖叫声\] 在文件被包装之前(例如,在创建多克图像或部署存档之前)必须运行 CLI . CLI 向捆绑文件的结尾插入一个注释和一个简短的函数以允许符号化,所以它需要 在包装之前发生.

此外, 如果您的应用版本只在构建时才为人所知, 您可以将它包含在相同的命令中, 以便它注入 进入捆绑。 如果您遵循这种方法, 调用时不包含应用软件 `initSDK` 由于该值需要 优先级 :

```sh
npx embrace-web-cli upload --app-version "APP_VERSION" -a "YOUR_EMBRACE_APP_ID" -t "YOUR_EMBRACE_UPLOAD_API_TOKEN" -p "JS_BUILD_PATH"
```

> \[注\] 目前我们只支持用函数关键字定义函数名的符号化 . 对于指定给常数或变量的函数,您仍然可以看到未同步的符号 . 行号和列号,连同文件名,将永远被符号化为原始来源.

## 配置自动仪器

SDK提供数个自动仪器出箱,以改变这些设备的行为(或禁用某些设备) 完全的) 你可以通过一个 `defaultInstrumentationConfig` 初始化 SDK 时的对象 :

```typescript
import { initSDK } from '@embrace-io/web-sdk';

initSDK({
  appID: 'YOUR_EMBRACE_APP_ID',
  appVersion: 'YOUR_APP_VERSION',
  defaultInstrumentationConfig: {
    omit: new Set(['@opentelemetry/instrumentation-fetch']),
  },
});
```

查看类型定义 `defaultInstrumentationConfig` 以查看整套配置选项.

对于更先进的定制,您也可以包括额外的仪器,只要它们符合 `Instrumentation` 接口 :

```typescript
import { initSDK } from '@embrace-io/web-sdk';

initSDK({
  appID: 'YOUR_EMBRACE_APP_ID',
  appVersion: 'YOUR_APP_VERSION',
  instrumentations: [myCustomInstrumentation],
});
```

## 自定义出口商

您可以设置自定义日志并追踪出口商, 并在初始化 SDK 时通过 。 出口商应: 配置以指向一个相容的 OTLP 端点,并包含该端点所需的任何信头,例如 授权。 由于这些导出请求将由浏览器提出, 也要求端点返回 相关CORS标题:

```typescript
import { OTLPLogExporter } from '@opentelemetry/exporter-logs-otlp-http';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';

initSDK({
  appID: 'YOUR_EMBRACE_APP_ID',
  appVersion: 'YOUR_APP_VERSION',
  spanExporters: [
    new OTLPTraceExporter({
      url: 'https://example.com/endpoint/for/traces',
      headers: {
        Authorization: 'Basic TOKEN',
      },
    }),
  ],
  logExporters: [
    new OTLPLogExporter({
      url: 'https://example.com/endpoint/for/logs',
      headers: {
        Authorization: 'Basic TOKEN',
      },
    }),
  ],
  defaultInstrumentationConfig: {
    network: {
      ignoreUrls: [
        'https://example.com/endpoint/for/traces',
        'https://example.com/endpoint/for/logs',
      ],
    },
  },
});
```

> \[尖叫声\] 拥抱会自动为网络请求创建跨度, 但因为 OTLP 导出本身会使网络 请求此选项可生成一个周期, 即导出网络请求所创建的周期, 然后导出该周期 创建另一个跨等.
> 
> 为避免这种情况,您可以配置网络仪器,以忽略您要导出到的 URL , 如 上面的片断.

## 包含 SDK 作为代码片段来自 CDN

我们建议你把我们的SDK列为普通npm依赖(参见: [快速启动](https://npmcn.com/package/%40embrace-io/web-sdk/#readme-quick-start)) (中文(简体) ). 如果你喜欢包含 sDK作为CDN的代码片段,您可以通过在您生成的 HTML 文件上添加以下脚本标记来做到这一点:

```html
<script src="https://cdn.jsdelivr.net/npm/@embrace-io/web-sdk" crossorigin="anonymous"></script>
```

注意:我们推荐您给特定版本打针,以避免打破更改. 喜欢:

```html
<script src="https://cdn.jsdelivr.net/npm/@embrace-io/web-sdk@X.X.X" crossorigin="anonymous"></script>
```

替换 `X.X.X` 包含您想要包含的 SDK 版本 。 检查可用的版本 打开 [无](https://www.npmjs.com/package/@embrace-io/web-sdk)。 。 。 .

我们建议你把这个脚本标记添加到 `<head>` 中的HTML文件,使其在应用程序代码之前加载。 这个会 将 SDK 暴露为全球变量 `EmbraceWebSdk` 编辑 `window` 对象。 脚本前需要添加此内容 使用sdk.

其余部分假设使用国家预防机制装置中的SDK, 此处需要作一些修改,以铭记 参考这些文件:

1.  从节点模块导入 sdk 已不再有效 。 相反,从全球范围参考 `window` 对象 :
    
    ```diff
    - import { initSDK, log, page, session, trace, user } from '@embrace-io/web-sdk';
    + const { initSDK, log, page, session, trace, user } = window.EmbraceWebSdk;
    ```
    
2.  我们的CLI工具在从CDN装入时不支持插入应用程序版本,因为在这种情况下,我们的SDK不是 与代码相捆绑,相反,您在初始化 sdk 时需要确保通过您的应用版本 实例如下:
    
    ```javascript
    initSDK({
      appVersion: '0.0.1',
      /*...*/
    });
    ```
    

### 同步装入

如果您喜欢同步加载SDK以避免屏蔽页面的渲染,您需要添加 跟随片断到您的 HTML 文件。 记得替换 `X.X.X` 您想要包含的 SDK 版本 :

```html
<script>
   !function(){window.EmbraceWebSdkOnReady=window.EmbraceWebSdkOnReady||{q:[],onReady:function(e){window.EmbraceWebSdkOnReady.q.push(e)}};let e=document.createElement("script");e.async=!0,e.crossOrigin="anonymous",e.src="https://cdn.jsdelivr.net/npm/@embrace-io/web-sdk@X.X.X",e.onload=function(){window.EmbraceWebSdkOnReady.q.forEach(e=>e()),window.EmbraceWebSdkOnReady.q=[],window.EmbraceWebSdkOnReady.onReady=function(e){e()}};let n=document.getElementsByTagName("script")[0];n.parentNode.insertBefore(e,n)}();
</script>
```

通过推迟SDK的装入,任何早期对SDK的呼叫都需要被包裹在 `onReady` 方法 :

```javascript
window.EmbraceWebSdkOnReady.onReady(() => {
  window.EmbraceWebSdk.initSDK({
    appVersion: '0.0.1',
    /*...*/
  });
});
```

这对于确保SDK在开始使用前被满载是必要的.

> \[尖叫声\] SDK可能会错过一些在SDK初始化前发射的早期遥测事件,如果使用这种方法的话.

### 运行 SDK 的多例

如果您在同一页上有多个应用程序并想要运行 SDK 的多个实例,您可以通过 为每个应用程序创建 SDK 实例。 确保旗帜 `registerGlobally` 设置为 `false` 何时 启动SDK.

```typescript
import { initSDK } from '@embrace-io/web-sdk';

const embraceSDK = initSDK({
  appID: 'YOUR_EMBRACE_APP_ID',
  appVersion: 'YOUR_APP_VERSION',
  registerGlobally: false, // Prevents the SDK from registering itself globally
});
```

由于SDK没有在全球注册,您需要使用 `embraceSDK` 实例访问 SDK 方法 以及财产.

```typescript
import { initSDK } from '@embrace-io/web-sdk';

const embraceSDK = initSDK({
  appID: 'YOUR_EMBRACE_APP_ID',
  appVersion: 'YOUR_APP_VERSION',
  registerGlobally: false, // Prevents the SDK from registering itself globally
});

// Use this
embraceSDK.log.message('This is a log message', 'info');

// Instead of
import { log } from '@embrace-io/web-sdk';

log.message('This is a log message', 'info');
```

一些仪器仍在全球注册,我们正积极地努力使每个设备都适合本地:

-   获取和 XHR 仪器补丁全局功能(`globalThis.fetch` 财务报告和审定财务报表 `XMLHttpRequest.prototype`) (中文(简体) ). 何时 在同一页上运行的多个 SDK 实例,每个实例都安装了自己的包装并生成跨度 每一个网络请求.
-   全局错误处理器会听到所有未处理的错误和拒绝, 所有 SDK 都会报告所有错误 没有被抓住.

## 网络跨度转发

SDK可以被配置为在向外发送的网络请求中注入一个痕量母头. 此标题包括 客户端追踪ID与该特定网络跨度相关。 在Enbrace后端,这些网络跨度就可以了 被传送到您选择的其他遥测提供者。 这样你就能一边看客户端 服务器侧式的,构成同一总体跟踪的一部分,以提供端到端的表示. 更多细节可以 发现于 [网络扩展转发文档页面](https://embrace.io/docs/data-forwarding/network-spans-forwarding/)。 。 。 .

这个功能的赋能和配置是通过我们的Enbrace仪表板完成的,所以不需要在其中设置 SDK可以打开它,但是有一些SDK侧面的配置使得特性无法意识到:

### 启用特定CORS请求

默认情况下 `traceparent` 发出CORS请求时不包含标题 。 这是因为服务器是 命中可能无法配置允许为 CORS 请求添加信头(参见 [访问控制- Allow 标题](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Access-Control-Allow-Headers)) (中文(简体) ). 您可以指定您想要转发 CORS 请求和允许您接受的特定 URL 将获取或 XHR 仪器配置为允许的字符串和正则列表后的额外标题 :

```typescript
import { initSDK } from '@embrace-io/web-sdk';

initSDK({
  appID: 'YOUR_EMBRACE_APP_ID',
  appVersion: 'YOUR_APP_VERSION',
  defaultInstrumentationConfig: {
    '@opentelemetry/instrumentation-fetch': {
      propagateTraceHeaderCorsUrls: [
        /example\.com/, // propagates for any CORS requests with URLs that match the regex
        'https://www.example.com/foo', // propagates for CORS requests to URLs that exactly match the string
      ],
    },
    '@opentelemetry/instrumentation-xml-http-request': {
      propagateTraceHeaderCorsUrls: [
        /example\.com/, // propagates for any CORS requests with URLs that match the regex
        'https://www.example.com/foo', // propagates for CORS requests to URLs that exactly match the string
      ],
    },
  },
});
```

### 冲突配置

SDK的特定配置与Network Span Transforming不相容,并将导致特性成为 设定时关闭 :

```typescript
import { initSDK } from '@embrace-io/web-sdk';

initSDK({
  appID: 'YOUR_EMBRACE_APP_ID',
  appVersion: 'YOUR_APP_VERSION',

  // The following are not supported alongside Network Span Forwarding and will cause that feature to turn off:
  // 1. Setting registerGlobally to false
  registerGlobally: false,
  // 2. Providing a custom propagator
  propagator: myCustomPropagator,
  // 3. Omitting both network instrumentations
  defaultInstrumentationConfig: {
    omit: new Set([
      '@opentelemetry/instrumentation-fetch',
      '@opentelemetry/instrumentation-xml-http-request',
    ]),
  },
});
```

### 屏蔽客户端

A 类 `blockNetworkSpanForwarding` 可用配置旗来屏蔽网络分页转发特性, 不论 已配置的服务器侧:

```typescript
import { initSDK } from '@embrace-io/web-sdk';

initSDK({
  appID: 'YOUR_EMBRACE_APP_ID',
  appVersion: 'YOUR_APP_VERSION',

  blockNetworkSpanForwarding: true,
});
```

## 在不拥抱的情况下使用

如果你不想把数据寄给Embrace 你只要在呼叫时省略了拥抱应用程序的ID `initSDK`。请注意 此例至少需要按照步骤配置一个自定义导出者 从 [自定义出口商](https://npmcn.com/package/%40embrace-io/web-sdk/#readme-custom-exporters) 或者SDK认为配置无效.

## 浏览器支持

SDK是作为模块被导入,由捆绑机转接. 我们提供一个ES2022模块版本,供使用 在现代建筑管道。 OpenTeleometry设定了当前ES2022的最小语言特性支持. 我们的默认无害环境管理 SDK也以此为目标,以确保兼容性. 详见 页:1 [打开几何文件](https://github.com/open-telemetry/opentelemetry-js#browser-support)。 。 。 .

我们还提供CDN版本,可转录到ES6/ES2015,与更古老的浏览器实现最大兼容.

## 解决问题

### 主要版本之间的升级

请看我们的 [升级指南](https://npmcn.com/package/%40embrace-io/web-sdk/UPGRADING.md) 具体步骤.

### 与 OTel 包的兼容性

SDK建于OpenTeleometry上方,因此可以与其他OTel库并用. **重要:新项目应使用OpenTeleomet 2.x.** OpenTeleomet 1.x支持仅限于SDK的1.x版本,这些版本被贬值.

如果您希望通过配置自定义资源、出口商、处理器或仪器来定制 SDK 行为, 您必须确保您使用与我们的 SDK 兼容的 OTel 软件包的版本 :

| 拥抱 Web SDK | 打开遥测 API | 核心 | 仪器和连接 |
| --- | --- | --- | --- |
| ^ 2. 0 | ^ 1.9.0 时 | ^2.0.3 (中文(简体) ) | \>=0.203.0<0.300.0> (中文(简体) ) |
| 1.8.2 国家 | ^ 1.9.0 时 | 1.30.1 (中文(简体) ) | 0.57.2 (中文(简体) ) |

关于SDK使用的依赖性完整清单,请参见: [软件包.json](https://npmcn.com/package/%40embrace-io/web-sdk/package.json)。 。 。 .

### 打开SDK的动词记录

默认情况下,SDK只会向控制台发送出错级别日志. 当 初始化情况如下:

```typescript
import { initSDK, DiagLogLevel } from '@embrace-io/web-sdk';

initSDK({
  appID: 'YOUR_EMBRACE_APP_ID',
  appVersion: 'YOUR_APP_VERSION',
  logLevel: DiagLogLevel.ALL,
});
```

此外,将SDK初始化为 `ConsoleLogRecordExporter` 财务报告和审定财务报表 `ConsoleSpanExporter` 出口商允许您接受 更详细地查看SDK出口的跨度和日志。 可以设立海关出口商, 在这种情况下,其输出将进行分批处理,或用自定义处理器包裹,以看到遥测输出时的输出 发射 :

```typescript
import { initSDK, DiagLogLevel } from '@embrace-io/web-sdk';
import {
  ConsoleLogRecordExporter,
  SimpleLogRecordProcessor,
} from '@opentelemetry/sdk-logs';
import {
  ConsoleSpanExporter,
  SimpleSpanProcessor,
} from '@opentelemetry/sdk-trace';

initSDK({
  appID: 'YOUR_EMBRACE_APP_ID',
  appVersion: 'YOUR_APP_VERSION',
  logLevel: DiagLogLevel.INFO,

  // setup as exporters to output with the same batching as when exporting to a collector endpoint
  spanExporters: [new ConsoleSpanExporter()],
  logExporters: [new ConsoleLogRecordExporter()],

  // OR, wrap exporters with simple processors to output as soon as telemetry is emitted
  spanProcessors: [new SimpleSpanProcessor(new ConsoleSpanExporter())],
  logProcessors: [new SimpleLogRecordProcessor(new ConsoleLogRecordExporter())],
});
```

### 仅客户端使用

Embrace SDK是为浏览器环境而设计的. 导入到服务器侧码( 如 Next.js 服务器组件, API 路由, 边缘中端软件) 不会产生运行时间错误, 因为 `initSDK` 检测非浏览环境和返回 `false`. SDK API 喜欢 `session` 财务报告和审定财务报表 `trace` 需要浏览器上下文,并且不会在服务器上运行.

为了取得最佳效果,导入并初始化SDK只使用客户端代码. Next.js 设置,包括 App 路由器和页面 路由器示例和构建配置,参见 [下一届](https://npmcn.com/package/%40embrace-io/web-sdk/NEXTJS.md)。 。 。 .

## 财务问题

### SDK 的数据如何导出

参见 [数据出口.md](https://npmcn.com/package/%40embrace-io/web-sdk/DATA_EXPORT.md) 关于数据如何从SDK输出的细节.

### 如何保护敏感数据

SDK提供了几个帮助保护敏感数据的选项,参见: 改为 [本准则](https://embrace.io/docs/web/best-practices/security-considerations/) 更多信息.

## 支助

如果你有特别建议或者发现一些不正确的东西 请打开 a 一个 [问题](https://github.com/embrace-io/embrace-web-sdk/issues/new) 由拥抱团队进行分解或接触 我们 [社区黑](https://community.embrace.io/) 直接,更快的援助.

## 捐款

请参看我们 [捐款指南](https://npmcn.com/package/CONTRIBUTING.md) 要开始.

## 常见问题

### @embrace-io/web-sdk 是什么？

拥抱 Web SDK

### 如何安装 @embrace-io/web-sdk？

在项目目录运行 npm install @embrace-io/web-sdk，或使用 pnpm add / yarn add / bun add。

### @embrace-io/web-sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @embrace-io/web-sdk 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @embrace-io/web-sdk 可以商用吗？

@embrace-io/web-sdk 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @embrace-io/web-sdk 的下载量有多少？

根据 npm 官方下载统计，@embrace-io/web-sdk 在 2026/10/14 – 2026/11/12 这 30 天内被下载 42,425 次，日均约 1,414 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @embrace-io/web-sdk 还在维护吗？

最新版本 2\.33\.0 发布于 2026/11/09（4 天前）；至今共发布 71 个版本，其中过去 12 个月发布了 31 个；首次发布于 2025/04/04。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。