# @birdie-so/snippet 中文文档

规范地址：https://npmcn.com/package/%40birdie-so/snippet/

版本：1\.5\.0
npm 元数据更新时间：2026-11-04T20:50:58.349Z
中文译文更新时间：2026-11-08T03:36:13.938Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40birdie-so/snippet
原文对照：https://npmcn.com/package/%40birdie-so/snippet/?lang=original
项目主页：https://docs.birdie.so/

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

- 包体积（解压后）：44.5 kB，4 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2025-04-23T21:50:35.641Z
- 最新版本发布：2026-11-04T20:50:58.072Z
- 近 30 天下载量：440523（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：21（近 12 个月 16 个）

## 中文简介

帮助将 Birdie 屏幕录制片段整合到现代JavaScript app中. 需要Birdie的账户.

## 安装

```sh
npm install @birdie-so/snippet
```

也可以使用：`pnpm add @birdie-so/snippet`、`yarn add @birdie-so/snippet`、`bun add @birdie-so/snippet`

## README

# @birnie-so/片段

使用现代框架等将 Birdie 屏幕记录片段轻松整合到您的应用程序中 **反应**, (中文(简体) ), **阴道**, (中文(简体) ), **角质**或平面 **Java 脚本** ——全面控制初始化,元数据,和事件钩.

> QQ 此软件包是整合 Birnie 的辅助工具 .  
> **你一定有Birdie的账户和一个有效的 `clientId` 用于使用此软件包.**  
> 没错 **不是靠自己来工作的** 访问 [https://app.birdie.so (中文(简体) )](https://app.birdie.so/) 要开始.

> 核心逻辑仍然从我们的CDN上载. 这个软件包只是方便集成和定制的轻快包装.

![npm](https://img.shields.io/npm/v/@birdie-so/snippet?label=npm%20version) ![license](https://img.shields.io/npm/l/@birdie-so/snippet)

* * *

## \* 安装

```bash
npm install @birdie-so/snippet
# or
yarn add @birdie-so/snippet
```

* * *

## QQ 快速启动

### 反应 / Vue / Angular / JS

```js
import { initBirdie } from "@birdie-so/snippet";

initBirdie({
  clientId: "YOUR_CLIENT_ID", // required
  contact: {
    email: "alex@empire.com" // required to get logs capture
  }

  // Optional metadata available to recordings
  metadata: {
    user: {
      id: "123",
      email: "user@example.com",
    },
  },

  // Optional setting to remove response bodies when collecting logs
  settings: {
    privacy: {
      mask_response_body: true
    }
  },

  // Optional hook once Birdie is ready
  onReady(birdie) {
    // you can register for the following events
    birdie.on("recorderOpen", (data) => {
      console.log("Recorder tab is opened", data);
    });
    birdie.on("start", (data) => {
      console.log("Recording started", data);
      birdie.metadata = { dynamicKey: "value" };
    });
    birdie.on("pause", (data) => {
      console.log("Recording paused", data);
    });
    birdie.on("resume", (data) => {
      console.log("Recording resumed", data);
    });
    birdie.on("stop", (data) => {
      console.log("Recording stopped", data);
    });
    birdie.on("restart", (data) => {
      console.log("Recording restarted", data);
    });
    birdie.on("captureStarted", (data) => {
      console.log("Capturing logs started", data);
    });
    birdie.on("captureStopped", (data) => {
      console.log("Capturing logs stopped", data);
    });
    birdie.on("recordingSent", (data) => {
      // data.link contains the link to the video
      console.log("A new recording has been sent", data);
    });
    birdie.on("recorderClose", (data) => {
      console.log("Recorder tab was closed", data);
    });
    birdie.on("error", (error) => {
      console.log("Something went wrong", error);
    });

    // you can also update data after initialization
    birdie.update({
        contact: {
            email: "john@empire.com"
        },
        metadata: {
            parameter: "value"
        }
    });
  }

});
```

* * *

## \* 如何运作

此软件包 :

-   以动态方式注入 Birnie CDN 片段 `clientId`。 。 。 .
-   设置全局 `window.birdieSettings` 装入前.
-   注册事件一旦Birdie SDK准备就绪(`window.birdie` 页:1.

你的原片段是这样的:

```html
<script>
  window.birdieSettings = {
    /* ... */
  };
</script>
<script src="https://cf.birdie.so/widget/embed/v3/YOUR_CLIENT_ID"
        integrity="sha384-7rC8M0J6DWvTouEw7T+c33g2KZtxGjkUe1CxynqsSx9fAHdgzhxr64PaLk7g4un0"
        crossorigin="anonymous"></script>
```

现在通过密码处理 `initBirdie()`。 。 。 .

* * *

## QQ 录音发射器(Web SDK)

从自己的按钮、链接或元素打开 Birdie 记录器—— a 支持窗体,一个帮助中心——添加 `launcher` 选项。 它装入了Web SDK (单独的,签名的脚本来自 `cdn.birdie.so/websdk/`在片段旁边. 没有选项时, 任何与发射装置有关的设备都不会被装入 .

```js
initBirdie({
  clientId: "YOUR_CLIENT_ID",
  contact: { email: "alex@empire.com" },

  launcher: true,
  // or: launcher: { trigger: "#record-button", tag: "support-form", autoClose: true, chip: true }

  onReady(birdie) {
    birdie.on("recorderOpen",  () => console.log("recorder window opened"));
    birdie.on("start",         () => console.log("recording started"));
    birdie.on("stop",          () => console.log("recording stopped"));
    birdie.on("recordingSent", (d) => console.log("sharing link:", d.link));
    birdie.on("recorderClose", () => console.log("recorder window closed"));

    birdie.launcher.open();    // also close(), toggle(), opened(), closeRecorder()
  },
});
```

带有类的任何元素 `birdieWebsdk_open` 点击时打开记录器; `trigger` 添加您自己的选择器 。 当录音机窗口打开时,一个小 右下芯片 (“ 记录打开 ” 、 “ 记录 ” 、 “ 发送 ” ) 将其带回 前; 它只出现在浏览器中, 记录器的浮控无法显示 开放(Safari), `chip: true` 到处看, `chip: false` 从来没有.

`onReady` 一旦片段运行时间或发射装置准备就绪, 因此它在一个只有发射装置才能运行的页面上工作(一个帮助中心在一个 域名片段未被授权)。 运载火箭的事件 `source: "websdk"`; 在运行这两页的页面上, 可以报告相同的录音 以各人各走一秒钟.

与 `launcher` 设定, `window.birdie` 从那一刻起存在 `initBirdie()` 返回,则 `birdie.on(...)` 可立即调用; `getBirdieInstance()` 返回时 `null` 直到一个运行时间实际上准备好了。 没有它,没有什么变化: 片段运行时间定义 `window.birdie` 和以前一样.

* * *

## \* 移动设备

Birdie不记录在电话或平板电脑上。 自兹 **1.2.3 联合国**, (中文(简体) ), `initBirdie()` 探测器 前面的装置(与Birdie运行时间的规则相同:iPhone/iPod,Android phone, iPad, Windows Phone/ BlackBerry, 和浏览器宣布 `userAgentData.mobile`和 **完全不装入片段** ——移动页面视图向博迪提出零请求.

您的集成代码不需要自行检查设备: 在手机上, `window.birdie` 仍作为具有相同表面的惰性物体提供(`on`, (中文(简体) ), `off`, (中文(简体) ), `emit`, (中文(简体) ), `update`, (中文(简体) ), `setContact`, (中文(简体) ), `setMetadata`, (中文(简体) ), `contact`, (中文(简体) ), `metadata`, (中文(简体) ), `settings`,则a `launcher` 谁 `open()` 发出一个 `error` 活动),以及 `onReady` 编号 : `getBirdieInstance()` 召回仍然开火。 事情从不发生, 因为没有记录 惰性物体带有不可假定的 `__birdieMobileStub: true` 如果你需要分辨清楚的话.

Android平板电脑和桌面浏览器的表现与以前完全相同.

* * *

## \* 分资源廉正

`initBirdie()` 装入 Birdie 加载器 **已版本, 不可改变的 URL** 和针 它与分资源正直。 浏览器将它接收并拒绝的文件拖走 除非散列匹配, 否则将执行它, 所以装入器—— 携带公钥 证明Birdie签了名的货单 不能被交换 即使是被一个人 控制服务它的主机.

从 `v2`,装载器还检查片段捆绑(`main.js`) 反对 签名清单中的sha384, 和捆绑检查它装入的每个文件 它,所以在你的页面上运行的一切 都通过内容验证.

从 `v3`,加载器携带的公钥属于生成的签名密钥 在AWS KMS内部,它从未离开过它,装入器只接受键的 签名. `v1` 财务报告和审定财务报表 `v2` 继续工作但信任一个更旧的密钥: 升级到此 释放到新的一个.

这个包裹里面的钉子,你的锁文件已经按内容把它钉了,所以 信任锚不是来自它保护的宿主.

| 装入器版本 | 網址 | 廉正(sha384) |
| --- | --- | --- |
| `v3` | `https://cf.birdie.so/widget/embed/v3/{CLIENT_ID}` | `sha384-7rC8M0J6DWvTouEw7T+c33g2KZtxGjkUe1CxynqsSx9fAHdgzhxr64PaLk7g4un0` |
| `v2` | `https://cf.birdie.so/widget/embed/v2/{CLIENT_ID}` | `sha384-4c5NWkB8H0CK3H/BaPcvusHR93UZ/JUqI5ofd1qTowWf9zCvnz+nzDNSg+5Opw8E` |
| `v1` | `https://cf.birdie.so/widget/embed/v1/{CLIENT_ID}` | `sha384-UpHM1+1SRGw5d/lkhatup8ShhdrItyJ50qC2whsmcKcl9Xzubnhc+Vq5TXcP8VnJ` |

随时自行核实:

```bash
curl -s -H "Origin: https://YOUR_APP_DOMAIN" https://cf.birdie.so/widget/embed/v3/YOUR_CLIENT_ID \
  | openssl dgst -sha384 -binary | openssl base64 -A
```

**片段更新不需要重新剪接 .** 新Birdie版本飞船通过 签名的装入器在运行时校验;装入器本身会改变 很少,当它发布 _新设_ 版本 (`v4`,而更年长的 继续接受服务——因此,申请必须 `v1`, (中文(简体) ), `v2` 或者说 `v3` 继续工作 直到它升级了这个软件包.

这个 `Origin` 上方标题重要:没有它(或来自尚未授权的域) 为您的客户端 ID) CloudFront 答"Birdie不是在这里运行" 脚本而不是装填器,而散列将不匹配.

SRI 是可选的: 如果您的设置无法使用, 请移除 `integrity` 财务报告和审定财务报表 `crossorigin` 属性从上面的标记(或加载未转换的 URL)。 这个 明确签名检查仍然适用.

* * *

## 高级

### 晚点去接波迪

```js
import { getBirdieInstance } from "@birdie-so/snippet";

getBirdieInstance((birdie) => {
  birdie.on("start", () => {
    console.log("Recording started!");
  });
});
```

或同步 :

```js
const birdie = getBirdieInstance();
if (birdie) {
  birdie.metadata = { key: "value" };
}
```

* * *

## 医生

完整文件和综合实例,访问 [我们的文件页面](https://docs.birdie.so/birdie-docs/request-screen-recordings/installation/snippet)

* * *

## ++ 辅助

需要帮忙吗? 联系我们 [支持@ birnie.so](mailto:support@birdie.so)

* * *

## 许可证

麻省理工学院

## 常见问题

### @birdie-so/snippet 是什么？

帮助将 Birdie 屏幕录制片段整合到现代JavaScript app中\. 需要Birdie的账户\.

### 如何安装 @birdie-so/snippet？

在项目目录运行 npm install @birdie-so/snippet，或使用 pnpm add / yarn add / bun add。

### @birdie-so/snippet 支持 TypeScript 吗？

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

### @birdie-so/snippet 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @birdie-so/snippet 可以商用吗？

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

### @birdie-so/snippet 的下载量有多少？

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

### @birdie-so/snippet 还在维护吗？

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