# @1sygnal/onesygnal-web-sdk 中文文档

规范地址：https://npmcn.com/package/%401sygnal/onesygnal-web-sdk/

版本：1\.0\.4
npm 元数据更新时间：2026-10-07T12:34:20.484Z
中文译文更新时间：2026-11-06T17:40:39.477Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%401sygnal/onesygnal-web-sdk
原文对照：https://npmcn.com/package/%401sygnal/onesygnal-web-sdk/?lang=original
项目主页：https://github.com/1Sygnal/1sygnal-web#readme
源码仓库：https://github.com/1Sygnal/1sygnal-web

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

- 包体积（解压后）：16.5 kB，6 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-08-20T15:33:24.293Z
- 最新版本发布：2026-10-07T12:34:20.144Z
- 近 30 天下载量：2559（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：4（近 12 个月 4 个）

## 中文简介

1 Sygnal Web SDK——薄载机+CDN托管的调查引擎

## 安装

```sh
npm install @1sygnal/onesygnal-web-sdk
```

也可以使用：`pnpm add @1sygnal/onesygnal-web-sdk`、`yarn add @1sygnal/onesygnal-web-sdk`、`bun add @1sygnal/onesygnal-web-sdk`

## README

# 1 系统网络 SDK

薄载器 + CDN 主持调查引擎,用于1次系统产品调查、事件跟踪和 用户身份.

## 安装

### 无

```bash
npm install @1sygnal/onesygnal-web-sdk
```

```typescript
import oneSygnal from '@1sygnal/onesygnal-web-sdk';

oneSygnal.init('your-api-key', { apiUrl: 'https://sdk-api.1sygnal.app' });
```

包裹有一个 **只默认导出** 没有 `{ init, track, identify }` 名称 输出.

### 脚本标签( 自发- init)

```html
<script
  src="https://repo.1sygnal.app/js/1sygnal.js"
  data-api-key="your-api-key"
  data-api-url="https://sdk-api.1sygnal.app"
></script>
```

## 使用量

### 跟踪事件

```typescript
oneSygnal.track('button_click', { id: 'cta' });
```

### 识别用户

```typescript
oneSygnal.identify('user-123', { plan: 'pro' });
```

还提供: `oneSygnal.logout()` 清除会话/用户状态,以及 `oneSygnal.setSurveysEnabled(enabled)` 在运行时切换调查.

### 倾听调查活动

```typescript
oneSygnal.on('survey:completed', (event) => {
  // handle completion
});
```

其他活动: `"survey:shown"`, (中文(简体) ), `"survey:step"`, (中文(简体) ), `"survey:dismissed"`。取消订阅 与 `oneSygnal.off(event, callback)`。 。 。 .

## 如何运作

`init()` 返回时 `void`而不是承诺,它注入了 `<script>` 装入全部 SDK 的标签 从 1Sygnal 的 CDN 捆绑到队列 `track`编号 :`identify`编号 :`on`/etc. 呼叫直到捆绑 装载和信号准备。 没什么 `await`; 在捆绑准备好之前打过电话 排队并重放。 这使勘测-触发修正和特征船 每个嵌入的站点立即, 没有依赖性起伏和重新部署.

### 移动安全区设置

底部/顶部调查使用情况 `env(safe-area-inset-*)` 来清理鼻孔和家 电话指标。 这些 `env()` 仅当页面选择通过 :

```html
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
```

`init()` 自动补丁( 待决) `viewport-fit=cover` 改为现有 `<meta name="viewport">`,或者如果页面没有,则添加一个),所以这是一个倒置,而不是 硬性要求——但将它设置在页面中 `<head>` 仍然建议,因为 在SDK负载前生效.

## 文档

全面整合指南: [https://docs.1sygnal.app (英语)](https://docs.1sygnal.app/)

## 其他 SDKs 软件

-   [iOS SDK (英语)](https://github.com/1Sygnal/1sygnal-ios-sdk)
-   [机器人 SDK](https://github.com/1Sygnal/1sygnal-android-sdk)

## 常见问题

### @1sygnal/onesygnal-web-sdk 是什么？

1 Sygnal Web SDK——薄载机\+CDN托管的调查引擎

### 如何安装 @1sygnal/onesygnal-web-sdk？

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

### @1sygnal/onesygnal-web-sdk 支持 TypeScript 吗？

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

### @1sygnal/onesygnal-web-sdk 支持 ESM 还是 CommonJS？

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

### @1sygnal/onesygnal-web-sdk 可以商用吗？

@1sygnal/onesygnal-web-sdk 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @1sygnal/onesygnal-web-sdk 的下载量有多少？

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

### @1sygnal/onesygnal-web-sdk 还在维护吗？

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