# @datadog/electron-sdk 中文文档

规范地址：https://npmcn.com/package/%40datadog/electron-sdk/

版本：1\.0\.0
npm 元数据更新时间：2026-10-29T09:34:12.524Z
中文译文更新时间：2026-11-11T13:21:56.920Z
软件包许可：未声明

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

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

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

- 包体积（解压后）：8.2 MB，34 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：electron \>=39
- 首次发布：2026-03-24T14:39:21.470Z
- 最新版本发布：2026-10-29T09:34:12.063Z
- 近 30 天下载量：862764（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：16（近 12 个月 16 个）

## 中文简介

用于电子应用的数据Dog SDK

## 安装

```sh
npm install @datadog/electron-sdk
```

也可以使用：`pnpm add @datadog/electron-sdk`、`yarn add @datadog/electron-sdk`、`bun add @datadog/electron-sdk`

## README

# 电子数据犬 SDK

电子应用程序的真正用户监测.

## 开始

### 先决条件

-   电能39+

### 安装

```bash
yarn add @datadog/electron-sdk
# or
npm install @datadog/electron-sdk
```

### 设置

Electron SDK在引擎盖下使用dd-trace来监视主过程并依靠浏览器SDK来监视渲染器过程.

```mermaid
graph TB
    subgraph Electron Application
        subgraph Renderer Process
            BP[Browser SDK]
        end

        subgraph Main Process
            DDT[dd-trace]
            SDK[Electron SDK]
        end
    end

    DD[(Datadog)]
    BP --> SDK
    DDT --> SDK
    SDK --> DD

    %% Styling
    classDef sdk fill:#fce8e6,stroke:#d93025
    classDef trace fill:#e6f4ea,stroke:#137333
    classDef browser fill:#fef7e0,stroke:#e37400
    classDef ext fill:#f3e8fd,stroke:#7627bb

    class BP browser
    class DDT trace
    class SDK sdk
    class DD ext
```

#### 主要流程设置

导入仪器输入点 **在此之前** `electron` 在您的主要进程中:

```ts
// src/main.ts
import '@datadog/electron-sdk/instrument';
import { app, BrowserWindow } from 'electron';
```

这些仪器是所需的电子API. `dd-trace` 以解析的配置初始化 `init()` 名为.

然后启动电子SDK,等待 `init` 在创建浏览器窗口之前 :

```ts
import { init } from '@datadog/electron-sdk';

await init({
  clientToken: '<CLIENT_TOKEN>',
  applicationId: '<APPLICATION_ID>',
  service: 'my-electron-app',
  site: 'datadoghq.com',
  allowedRendererHosts: ['*'], // required: restrict to specific hostnames in production
});
```

> **推迟的提示:** 窗口之前打开 `init()` 解析在重新装入之前不会被跟踪。 等待最终用户的同意,打电话 `init()` 启动时使用 `trackingConsent: 'pending'` 而不是推迟(见 [跟踪同意](https://npmcn.com/package/%40datadog/electron-sdk/#readme-tracking-consent)) (中文(简体) ).

#### 渲染器进程设置

为了监视渲染器过程,您必须 [设置浏览器 SDK](https://docs.datadoghq.com/real_user_monitoring/application_monitoring/browser/setup/) 在由渲染器装入的页面中.

#### 渲染器日志收集

由浏览器 Logs SDK 组装的日志通过Electron Bridge 转发,由上传 主要进程。 在您的渲染器包中安装浏览器日志 SDK :

```bash
yarn add @datadog/browser-logs
# or
npm install @datadog/browser-logs
```

在您想要收集日志的每个渲染器页面中初始化 :

```ts
import { datadogLogs } from '@datadog/browser-logs';

datadogLogs.init({
  clientToken: '<CLIENT_TOKEN>',
  site: 'datadoghq.com',
  service: 'my-electron-app',
  forwardErrorsToLogs: true,
});
```

浏览器 Logs SDK 探测到被 Electron SDK 所暴露的桥并发送到主 进程,而不是直接上传它们。 见 [浏览器日志设置指南](https://docs.datadoghq.com/logs/log_collection/javascript/) 额外费用 渲染器配置选项 .

在主要过程中配置 Electron SDK 上的渲染器-log 采样 :

```ts
await init({
  clientToken: '<CLIENT_TOKEN>',
  applicationId: '<APPLICATION_ID>',
  service: 'my-electron-app',
  site: 'datadoghq.com',
  allowedRendererHosts: ['*'],
  logsSampleRate: 25, // forwards 25% of renderer logs
});
```

`logsSampleRate` 默认为 `100` 并独立应用到每个桥接的日志上。 这是独立的 从卢比 `sessionSampleRate`。浏览器日志 SDK 不应用自己的日志 `sessionSampleRate` 在桥上 模式,因此电子设置具有权威性.

#### Bundler 插件

SDK仪器 Electron在被装入时需要正确的模块加载顺序. SDK提供捆绑插件,以确保这在所有环境中都有效.

每个插件都接受 `copyRuntimeDependencies`控制它是否复制SDK, `dd-trace`, (中文(简体) ), 及其运行时间对构建输出的依赖性。 默认为 `false`: 应用程序 软件包必须在软件包中包含这些依赖性。 设定 `copyRuntimeDependencies: true` 仅作为包件器无法显示时的最佳相容性回落.

保留 `@datadog/electron-sdk` 在应用程序的制作中 `dependencies`它带来 `dd-trace` 作为运行时间依赖。 已经使用的应用程序 `copyRuntimeDependencies: false` 工作时 包件组装不需要改变配置 .

##### 电子福尔格

当使用 Forge 的 Vite 或 Webpack 插件时, 保留 `copyRuntimeDependencies` 禁用和配置 伪造到包根 `node_modules` 随同捆绑器输出,电子包件器可以相接 生产依赖性通常.

**福吉维特:** 添加一个 `ignore` 函数改为 `packagerConfig` 内 `forge.config.ts`数字 :

```ts
packagerConfig: {
  ignore: (file) => {
    if (!file) return false;
    return !/^[/\\](?:\.vite|node_modules)(?:[/\\]|$)/.test(file);
  },
},
```

**Forge Web 软件包 :** 使用同样的配置 `.webpack` 改为 `.vite`数字 :

```ts
packagerConfig: {
  ignore: (file) => {
    if (!file) return false;
    return !/^[/\\](?:\.webpack|node_modules)(?:[/\\]|$)/.test(file);
  },
},
```

使用 `datadogVitePlugin()` 或者说 `new DatadogWebpackPlugin()` 没有复制选项。 见 [完成电子福热设置指南](https://npmcn.com/package/%40datadog/electron-sdk/docs/RUNTIME_DEPENDENCIES.md) 完整示例和软件包 经理要求.

##### 其他包装器

`copyRuntimeDependencies` 默认为 `false` 用于每个 Datadog 捆绑插件。 保留默认值 配置应用程序包以进行生产依赖。 电子和平面 Forge 在将应用程序源包装时默认已经这样做; 将行为保存在 定制包装配置.

在主进程捆绑器配置中添加相应的 Datadog 插件.

**维特** (包括电子视频和独立视频):

```ts
// vite config
import { defineConfig } from 'vite';
import { datadogVitePlugin } from '@datadog/electron-sdk/vite-plugin';

export default defineConfig({
  plugins: [datadogVitePlugin()],
});
```

**网页包 :**

```ts
// webpack config
const { DatadogWebpackPlugin } = require('@datadog/electron-sdk/webpack-plugin');

module.exports = {
  plugins: [new DatadogWebpackPlugin()],
};
```

**兴建 :**

```ts
// esbuild config
import { datadogEsbuildPlugin } from '@datadog/electron-sdk/esbuild-plugin';

await esbuild.build({
  plugins: [datadogEsbuildPlugin()],
});
```

## 可用特性

-   **会议** - 基于会场的活动分组
-   **RUM 视图** – 每个主要进程实例一个观点
-   **RUM 错误** ——主要过程中抓取节点出错和相撞
-   **RUM 资源** ——从主要流程网络呼叫中获取 RUM 资源
-   **追踪** ——抓取网络呼叫的痕迹,命令执行主进程
-   **渲染器事件** ——通过浏览器SDK从渲染器过程中捕获 RUM 事件
-   **自定义持续时间** ——测量主要过程中用户定义的期限
-   **渲染器剖析** - 从渲染器的网页上收集联署材料自我显示数据,并将其与RUM联系起来
-   **会话重放** ——主要过程中的记录渲染器UI会话并将其与 RUM 视图相链接
-   **全球背景** – 从主进程给 RUM 事件附加自定义属性
-   **用户账户信息( A)** 在所有 RUM 事件和跟踪中附加用户和账户身份
-   **行动监测** _(实验性)_ – 跟踪启动/ 成功/ 失败步骤 关键用户创建工作流程
-   **事件过滤和剪切** 修改或丢弃 RUM 事件 `beforeSendRum`
-   **跟踪同意** 根据最终用户的同意收集和发送数据
-   **来源地图** ——解析您原始源代码的主进程和渲染器堆栈痕迹

### 事件过滤和剪切

使用 `beforeSendRum` 在将 RUM 事件发送到 Datadog 之前检查全部组装的主处理和渲染器:

```ts
await init({
  // ...
  beforeSendRum: (event, { source }) => {
    if (event.type === 'error') {
      event.error.message = event.error.message.replace(/token=[^&\s]+/g, 'token=[REDACTED]');
      event.error.stack = event.error.stack?.replace(/token=[^&\s]+/g, 'token=[REDACTED]');
    }
    if (source === 'main' && event.context?.internal === true) {
      return false;
    }
    return true;
  },
});
```

仅返回 `false` 丢弃事件。 视图、 执行上下文和本地崩溃事件无法丢弃 。 这个 可编辑字段为:

-   所有事件 : `context`, (中文(简体) ), `service`, (中文(简体) ), `version`, (中文(简体) ), `view.name`, (中文(简体) ), `view.url`, (中文(简体) ), `view.referrer`,以及 `execution_context.name`
-   视图 : `view.performance.lcp.resource_url`
-   错误 : `error.message`, (中文(简体) ), `error.stack`, (中文(简体) ), `error.handling_stack`, (中文(简体) ), `error.resource.url`, (中文(简体) ), `error.fingerprint`,以及 `_dd.debug_ids`
-   资源: `resource.url`, GraphQL 变量、请求/答复信头和 WebSocket 近似理由和协议
-   行动: `action.target.name`
-   长任务:脚本源 URL,引用者,以及 `_dd.debug_ids`

事件身份、会话、应用和其他字段保持不变。 回调错误已被记录, 事件是 仍然发送。 可编辑的字符串字段必须保持字符串; 使用空字符串清除一个字符串, 因为删除或指定 `null` 或者说 `undefined` 被忽略。 回调是同步的,应该保持快. 它不会自动检测PII.

渲染器事件可能首先通过浏览器SDK `beforeSend`然后通过Electron的 `beforeSendRum` 之后 主工艺浓缩。 在此阶段过滤它们可防止上传, 但不会撤销浏览器计数器、 生命周期 效果,或已经发生的电会话活动。 Spans不会被传到这个召回.

### 跟踪同意

为了帮助您遵守GDPR和CCPA等法规,SDK根据终端用户收集并发送数据 跟踪同意 :

| 数值 | 行为 |
| --- | --- |
| `'granted'` (默认) | 收集并发送数据. |
| `'pending'` | 数据收集后保存在磁盘上,如果同意,则发送数据,如果拒绝,则删除数据. |
| `'not-granted'` | 新数据既没有保存也没有发送。 早先经同意而储存的数据仍予发送. |

以启动时已知的同意初始化 SDK, 并在最终用户回答时更新 :

```ts
import { init, setTrackingConsent } from '@datadog/electron-sdk';

await init({
  // ...
  trackingConsent: 'pending',
});

// Once the end user has answered the consent prompt:
setTrackingConsent(accepted ? 'granted' : 'not-granted');
```

-   拒绝同意结束届会 `'pending'` 或者说 `'granted'` 开始一个新的。 移动间 `'pending'` 财务报告和审定财务报表 `'granted'` 保持会话.
-   RUM 事件、日志、跨度、剖面和会话重放记录,在拒绝同意时开始,或等待 拒绝的,即使经再次同意后才报告,也不予发送.
-   主要程序请求在等待同意时带有跟踪头,如批准时,以便其跟踪 如果获得同意,则链接到发送的数据。 在拒绝同意的情况下,它们没有携带任何物品.
-   SDK不恢复下一次发射时的同意:每次发射时通过. 在等待同意时保存的数据 如果没有作出决定,则在下一次发射时被删除.
-   打电话 `setTrackingConsent()` 一次 `init()` 已经解决:可以忽略早先的一次呼吁.
-   无效 `trackingConsent` 中止 `init()`,并传递到无效值 `setTrackingConsent()` 处理方式为 `'not-granted'`。 。 。 .
-   SDK启动"Electron"的"坠机记者"(Electron's crash reporter),该记者无论同意与否,都在当地写出"本土坠机垃圾". 接下来 发射时,坠机情况与其他数据一样,由发生时的同意判断,然后发送、保存或投放 (b) 不论哪种方式,其倾销均被删除.

在主要过程中设定同意: `allowedRendererHosts` 到达数据犬通过 ,而其他渲染器则单独运行浏览器SDK `trackingConsent`中线 制造器,浏览器SDK没有被告知同意并不断收集,所以:

-   请其追踪( A)`allowedTracingUrls`不论同意与否,都带有追踪头.
-   当在拒绝后表示同意时,打开页面的视图随下一次更新而移动到新会话,以便 该会话出现在 Datadog 中。 作为上述规则的例外,即使该观点始于 拒绝同意,或等待批准,但从开始算起。 上届会议不再 列出它。 在新的会话中,页面会话回放只能从它的下个视图回放.

### 自定义持续时间

记录已知持续时间, 或在开始和停止通话之间测量持续时间 :

```ts
import { addDurationVital, startDurationVital, stopDurationVital } from '@datadog/electron-sdk';

addDurationVital('database.migration', {
  startTime: Date.now() - 1_500,
  duration: 1_500,
  context: { database: 'documents' },
});

startDurationVital('document.open', {
  vitalKey: 'document-42',
  context: { source: 'recent-files' },
});
await openDocument();
stopDurationVital('document.open', {
  vitalKey: 'document-42',
  context: { result: 'success' },
});
```

传入API的时代以毫秒计. 使用 `vitalKey` 用于测量同一名称的重叠持续时间; 它确定测量,但不包括在事件之中。 必须在同一进程中开始并停止衡量。 在渲染器过程中,使用等同的 `@datadog/browser-rum` APIs直接发布.

### 全球背景

将主过程的自定义属性附加到所有之后的RUM事件上,包括渲染器事件.

```ts
import {
  setGlobalContext,
  setGlobalContextProperty,
  removeGlobalContextProperty,
  clearGlobalContext,
} from '@datadog/electron-sdk';

setGlobalContext({ team: 'checkout', build: '1.2.3' });

// Update one attribute, leaving the others untouched
setGlobalContextProperty('feature_flag', 'new-cart');
removeGlobalContextProperty('feature_flag');

clearGlobalContext();
```

事件属性被发送 `context` 字段. `setGlobalContext` 替换整个上下文; 使用 `setGlobalContextProperty` 以更改单一属性。 设置属性到 `null` 移除它,就像 `addUserExtraInfo`。 。 。 .

通过浏览器 SDK 设置的渲染器进程保持自身的全球背景 `datadogRum.setGlobalContext`。两者在渲染器事件上合并,而渲染器的价值在相冲突的密钥上取胜.

### 用户账户信息( A)

在之后所有 RUM 事件和主要过程的痕迹中附加用户和账户身份. SDK传播上下文以自动覆盖和渲染RUM事件.

```ts
import { setUserInfo, clearUserInfo, addUserExtraInfo } from '@datadog/electron-sdk';
import { setAccountInfo, clearAccountInfo, addAccountExtraInfo } from '@datadog/electron-sdk';

// On login
setUserInfo({ id: 'user-123', name: 'Alice', email: 'alice@example.com' });
setAccountInfo({ id: 'account-456', name: 'Acme Corp' });

// Enrich with custom attributes
addUserExtraInfo({ plan: 'premium', role: 'admin' });
addAccountExtraInfo({ tier: 'enterprise', region: 'us' });

// Remove a custom attribute
addUserExtraInfo({ role: null });

// On logout
clearUserInfo();
clearAccountInfo();
```

### 行动监测 _(实验性)_

监控操作允许您通过发件对等跟踪关键用户界面工作流程(登录、取出、文件上传、视频回放等)的生命周期 `start` 编号 : `end` 步骤。 后端与步骤相关 `name` (和可选) `operationKey`),并被曝光为RUM UI中的单项行动.

> QQ 此 API 在预览中, 签名可能会在稳定发布前被更改 .

```ts
import { startOperation, succeedOperation, failOperation } from '@datadog/electron-sdk';

// Simple operation
startOperation('checkout');
try {
  await runCheckout();
  succeedOperation('checkout');
} catch (error) {
  failOperation('checkout', 'error');
}

// Parallel operations sharing a name — distinguished by `operationKey`
startOperation('upload', { operationKey: 'profile_pic' });
startOperation('upload', { operationKey: 'cover_photo' });
succeedOperation('upload', { operationKey: 'profile_pic' });
failOperation('upload', 'abandoned', { operationKey: 'cover_photo' });
```

渲染器进程继续使用 `@datadog/browser-rum` 直接(与 `feature_operation_vital` 实验旗启用于其init上). API 签名完全匹配, 这样您就可以在一个过程中启动一个操作, 在另一个过程中完成它 —— 后端与步骤相关 `name` + 键 `operationKey`。 。 。 .

### 渲染器剖析

浏览器 SDK (通过 [JS 自我介绍 API](https://developer.mozilla.org/en-US/docs/Web/API/JS_Self-Profiling_API)用于渲染器页面,并将其与 RUM 视图和长任务相链接.

**1\. 允许从主要进程进行剖析.** 设定 `profilingSampleRate` 在SDK电上 `init()`数字 :

```ts
await init({
  clientToken: '<CLIENT_TOKEN>',
  applicationId: '<APPLICATION_ID>',
  site: 'datadoghq.com',
  service: 'my-electron-app',
  allowedRendererHosts: ['*'],
  profilingSampleRate: 100, // percentage of sampled sessions that are profiled (0–100)
});
```

Electron SDK拥有剖面取样决定权 `profilingSampleRate` 在制造器中 `datadogRum.init` 没有效果.

**2\. 为制造者服务 `js-profiling` 文件政策.**

《联合来文》的自我介绍只有在与《任择议定书》一起发送网页时才提供 `Document-Policy: js-profiling` HTTP 响应头. 因为无法将响应信头附在 `file://` 协议,在可以设置标题的协议上为渲染器服务:

-   通过自定义协议 [`protocol.handle`](https://www.electronjs.org/docs/latest/api/protocol#protocolhandlescheme-handler)
-   本地的 HTTP 服务器 (`http://localhost:<port>`(中文(简体) )

使用自定义协议的,也必须登记为特权(`standard` 财务报告和审定财务报表 `secure`(中文(简体) ) _在此之前_ 该应用程序已经就绪, 否则JS自导自出API连信头都没有

```ts
import { protocol } from 'electron';

protocol.registerSchemesAsPrivileged([
  { scheme: 'app', privileges: { standard: true, secure: true, supportFetchAPI: true } },
]);
```

### 会话重放

浏览器 SDK 记录了渲染器 UI ([会话重放](https://docs.datadoghq.com/real_user_monitoring/session_replay/browser/)),并将记录流到主进程,它缓冲,压缩,并上传这些记录——与你的 RUM 视图相关.

**1\. 启用主要进程的会话重放.** 设定 `sessionReplaySampleRate` 在SDK电上 `init()`数字 :

```ts
await init({
  clientToken: '<CLIENT_TOKEN>',
  applicationId: '<APPLICATION_ID>',
  site: 'datadoghq.com',
  service: 'my-electron-app',
  allowedRendererHosts: ['*'],
  sessionReplaySampleRate: 100, // percentage of sampled sessions that record replay (0–100)
  defaultPrivacyLevel: 'mask', // 'mask' | 'allow' | 'mask-user-input'
});
```

Electron SDK拥有回放采样决定并进行上传. `sessionReplaySampleRate` 以儿童身份适用 `sessionSampleRate`,所以与 `sessionSampleRate: 0` 没有会话记录重放 。 这个 `defaultPrivacyLevel` 这里的设定通过桥面传播到渲染器记录器上,因此口罩强制端到端.

**2\. 在渲染器的浏览器SDK中启用会话重放.** 在渲染器装入的页面中,初始化 `@datadog/browser-rum` 重新播放会话

```ts
import { datadogRum } from '@datadog/browser-rum';

datadogRum.init({
  clientToken: '<CLIENT_TOKEN>',
  applicationId: '<APPLICATION_ID>',
  site: 'datadoghq.com',
  service: 'my-electron-app',
});
```

电子SDK广告 `records` 因此,浏览器SDK流将记录重放到主进程,而不是将记录本身上传——不 `startSessionReplayRecording()` 需要打电话。 见 [渲染器进程设置](https://npmcn.com/package/%40datadog/electron-sdk/#readme-renderer-process-setup) 用于一般浏览器 SDK 配置.

### 来源地图

例如,在电子应用程序中收集的堆栈跟踪和URL包含该应用程序的安装路径 `/Users/alice/Applications/MyApp.app/Contents/Resources/app.asar/dist/main/index.js` 在主要进程中,或 `file:///Users/alice/…/app.asar/dist/renderer/index.js` 在一个制作器。 这些路径随每次安装而变化,因此它们从不匹配构建时上传的源地图,并暴露了用户的安装目录.

SDK 重写应用程序路径( 由 `app.getAppPath()`改为: `/` 在它离开机器之前的每一个事件上:上面的帧变成 `/dist/main/index.js` 财务报告和审定财务报表 `/dist/renderer/index.js`。只重写应用程序路径:其他本地路径,如用户数据文件夹中或应用程序外的文件,按原样发送. 从自定义协议中装入的渲染器 URL `http(s)://` 未包含安装路径,但保持不变.

**1\. 生成源地图及其源地.** 配置您的捆绑器以发送嵌入原始代码的源地图( S)`sourcesContent`如本报告所述 [浏览器源地图指南](https://docs.datadoghq.com/real_user_monitoring/guide/upload-javascript-source-maps/)。如果主进程由 `tsc` 没有捆绑,设置两个 `sourceMap: true` 财务报告和审定财务报表 `inlineSources: true`,否则会堆叠痕迹解析度,但没有显示代码片段.

**2\. 对主要工艺和制造器使用不同的服务.** 一旦程序路径被重写,主进程和一个渲染器都可以同时报告相同的路径,例如: `/dist/index.js` 当两者都建为 `dist/`. Datadog按服务、版本和路径查看源地图,所以分开的服务将它们分开: `service` 传到电源SDK `init()`,和 `service` 转到浏览器 SDK `init()`设置 `version` 在电子SDK和浏览器SDK中 `init()`: 它不是默认设置的, 而上传的 `--release-version` 一定和它相符.

**3\. 上传源地图 [`datadog-ci`](https://github.com/DataDog/datadog-ci)**,按其 [安装指南](https://github.com/DataDog/datadog-ci/blob/master/packages/datadog-ci/README.md#how-to-install-the-cli) (dev 依赖,全局安装或独立二进制). 这个 `--service` 财务报告和审定财务报表 `--release-version` 必须匹配 SDK 配置,以及 `--minified-path-prefix` 必须是上传文件在堆栈跟踪中显示的路径。 运行 `datadog-ci` 从您 git 工作树上发送寄存器 URL 和上传源的输入, 因此错误跟踪将堆栈框架链接到您的代码 。 下面的例子假设一个应用软件包 `dist/` 文件夹.

主要进程,构建到 `dist/main/`数字 :

```sh
datadog-ci sourcemaps upload ./dist/main \
  --service my-electron-app-main \
  --release-version "$VERSION" \
  --minified-path-prefix /dist/main/
```

装入自 `file://`,建为 `dist/renderer/`数字 :

```sh
datadog-ci sourcemaps upload ./dist/renderer \
  --service my-electron-app-renderer \
  --release-version "$VERSION" \
  --minified-path-prefix /dist/renderer/
```

从自定义协议中装入的渲染器(例如需要浏览器SDK >= 7.9.0) `app://app/` 服务文件 `dist/renderer/`数字 :

```sh
datadog-ci sourcemaps upload ./dist/renderer \
  --service my-electron-app-renderer \
  --release-version "$VERSION" \
  --minified-path-prefix app://app/
```

装入自 `http(s)://`,例如服务于 `dist/renderer/` 其根源:

```sh
datadog-ci sourcemaps upload ./dist/renderer \
  --service my-electron-app-renderer \
  --release-version "$VERSION" \
  --minified-path-prefix /
```

## API 密码

### `init(config: InitConfiguration): Promise<boolean>`

初始化 SDK. 每次发射都打一次电话,然后再打给其他API 回返 `true` 关于成功, `false` 如果配置无效.

### `setTrackingConsent(consent: TrackingConsent): void`

设定终端用户的跟踪同意 : `'granted'`, (中文(简体) ), `'pending'` 或者说 `'not-granted'`。见 [跟踪同意](https://npmcn.com/package/%40datadog/electron-sdk/#readme-tracking-consent)。 。 。 .

### `setGlobalContext(context: Record<string, unknown>): void`

替换所有RUM事件所附带的全局背景.

### `getGlobalContext(): Record<string, unknown>`

返回当前全球背景,或 `{}` 如果没有设定.

### `setGlobalContextProperty(key: string, value: unknown): void`

设置一个单一的全局上下文属性,使其他属性不受影响.

### `removeGlobalContextProperty(key: string): void`

删除单个全局上下文属性 .

### `clearGlobalContext(): void`

从随后的事件中删除所有全局背景属性 .

### `setUserInfo(user: UserInfo & { id: string }): void`

设置用户身份 。 用户与所有之后的RUM事件和跨度相接. 一个 `id` (a) 没有电话的电话会被警告而忽略.

```ts
interface UserInfo {
  id?: string;
  name?: string;
  email?: string;
  extraInfo?: Record<string, unknown>;
}
```

### `getUserInfo(): UserInfo | undefined`

返回当前用户的副本,或 `undefined` 如果没有设定.

### `clearUserInfo(): void`

从随后的所有事件中删除用户 .

### `addUserExtraInfo(extraInfo: Record<string, unknown>): void`

合并用户的自定义属性 `extraInfo`设置密钥 `null` 来取出它。 之前也做过 `setUserInfo` 称为 —— 当用户时有用 `id` 源自别处(例如: `anonymous_id`) (中文(简体) ). 标准字段( E)`id`, (中文(简体) ), `name`, (中文(简体) ), `email`)此处被忽略.

### `setAccountInfo(accountInfo: AccountInfo): void`

设置账户身份 。 一个 `id` 需要时间.

```ts
interface AccountInfo {
  id: string;
  name?: string;
  extraInfo?: Record<string, unknown>;
}
```

### `getAccountInfo(): AccountInfo | undefined`

返回往来账户副本,或 `undefined` 如果没有设定.

### `clearAccountInfo(): void`

从所有后续事件中删除账户 .

### `addAccountExtraInfo(extraInfo: Record<string, unknown>): void`

将自定义属性合并到账户中 `extraInfo`设置密钥 `null` 来取出它。 要求数 `setAccountInfo` 被调用。 标准字段( E)`id`, (中文(简体) ), `name`)此处被忽略.

### `addError(error: unknown, options?: ErrorOptions): void`

报告手动处理的错误 .

```ts
import { addError } from '@datadog/electron-sdk';

try {
  riskyOperation();
} catch (error) {
  addError(error, { context: { component: 'sync' } });
}
```

### `addDurationVital(name: string, options: AddDurationVitalOptions): void`

记录一个关键自定义持续时间,明确起始时间和持续时间,以毫秒计.

### `startDurationVital(name: string, options?: DurationVitalOptions): void`

开始测量自定义的持续时间 就从同一个开始另一个关键 `name` 财务报告和审定财务报表 `vitalKey` 替换待定的计量.

### `stopDurationVital(name: string, options?: DurationVitalOptions): void`

停止并记录一个待定的定制期限至关重要。 从开始和停止通话开始的选项被深深地合并,停止值优先. 阻止未知生命力没有影响.

```ts
interface DurationVitalOptions {
  /** Distinguishes parallel measurements sharing the same `name`. */
  vitalKey?: string;
  /** Free-form attributes attached to the event. */
  context?: Record<string, unknown>;
  /** Free-form description attached to `vital.description`. */
  description?: string;
}

interface AddDurationVitalOptions extends DurationVitalOptions {
  /** Unix timestamp in milliseconds. */
  startTime: number;
  /** Duration in milliseconds. */
  duration: number;
}
```

### `startOperation(name: string, options?: FeatureOperationOptions): void`

启动RUM操作步骤. 每对一 `startOperation` 和一个 `succeedOperation` 或者说 `failOperation`启用 `options.operationKey` 以区分共享的平行操作 `name`。 。 。 .

> 说明: `name` 需要,只应包含字母、数字, `_`, (中文(简体) ), `.`, (中文(简体) ), `@`, (中文(简体) ), `$`, (中文(简体) ), `-`。 。 。 .

### `succeedOperation(name: string, options?: FeatureOperationOptions): void`

记录成功完成 RUM 操作. 传出同样的 `name` (和 `operationKey`(如果有的话) 用来启动它.

### `failOperation(name: string, failureReason: FailureReason, options?: FeatureOperationOptions): void`

记录一次RUM行动的失败. `failureReason` 必须是其中之一 `'error' | 'abandoned' | 'other'`。 。 。 .

```ts
type FailureReason = 'error' | 'abandoned' | 'other';

interface FeatureOperationOptions {
  /** Distinguishes parallel operations sharing the same `name`. */
  operationKey?: string;
  /** Free-form attributes merged into the event's `context`. */
  context?: Record<string, unknown>;
  /** Free-form description attached to `vital.description`. */
  description?: string;
}
```

> **被贬去的别名.** 早期审查名称 `startFeatureOperation` 编号 : `succeedFeatureOperation` 编号 : `failFeatureOperation` 被保留为向后兼容的已贬值的别名。 他们向上面的未固定名称转发并发出一次性运行警告. 他们将在下一次主要释放中被清除——迁移到 `startOperation` 编号 : `succeedOperation` 编号 : `failOperation`。 。 。 .

### 配置选项

| 选项 | 类型 | 需求 | 默认 | 说明 |
| --- | --- | --- | --- | --- |
| `clientToken` | `string` | 对 | —— 说 | 数据犬客户端符 |
| `applicationId` | `string` | 对 | —— 说 | RUM 应用程序标识 |
| `site` | `string` | 对 | —— 说 | 数据犬站点(如:. `datadoghq.com`, (中文(简体) ), `datadoghq.eu`, (中文(简体) ), `us3.datadoghq.com`, (中文(简体) ), `us5.datadoghq.com`, (中文(简体) ), `ap1.datadoghq.com`, (中文(简体) ), `ddog-gov.com`, (中文(简体) ), `us2.ddog-gov.com`(中文(简体) ) |
| `service` | `string` | 对 | —— 说 | 服务名称 |
| `env` | `string` | 没有 | —— 说 | 应用环境 |
| `version` | `string` | 没有 | —— 说 | 应用程序版本 |
| `sessionSampleRate` | `number` | 没有 | `100` | 收集的会议百分比(0-100). `0` 不收集会话; `100` 收集所有会话. |
| `trackingConsent` | `'granted' | 'pending' | 'not-granted'` | 没有 | `'granted'` | 最终用户的初步跟踪同意。 见 [跟踪同意](https://npmcn.com/package/%40datadog/electron-sdk/#readme-tracking-consent)。 。 。 . |
| `logsSampleRate` | `number` | 没有 | `100` | 每个日志独立抽样的桥接成像仪日志转发(0-100)的百分比。 在桥模式下, 将替换浏览器日志 `sessionSampleRate`。 。 。 . |
| `traceSampleRate` | `number` | 没有 | `100` | 在无时保留的主要进程跟踪百分比 `traceSamplingRules` 规则匹配( 0– 100) . |
| `traceSamplingRules` | `TraceSamplingRule[]` | 没有 | `[]` | 主过程痕迹的有序采样规则. 第一个匹配规则决定要保存的痕迹的百分比; 未匹配的痕迹使用 `traceSampleRate`。 。 。 . |
| `sessionReplaySampleRate` | `number` | 没有 | `0` | 记录会话重播的抽样会议的百分比(0-100). `0` 禁用渲染器会话重放 。 作为儿童申请 `sessionSampleRate`。 。 。 . |
| `profilingSampleRate` | `number` | 没有 | `0` | 介绍的抽样会议的百分比(0-100). `0` 无法配置渲染器。 作为儿童申请 `sessionSampleRate`。见 [渲染器剖析](https://npmcn.com/package/%40datadog/electron-sdk/#readme-renderer-profiling)。 。 。 . |
| `batchSize` | `'SMALL' | 'MEDIUM' | 'LARGE'` | 没有 | `'MEDIUM'` | 提前旋转批次文件的字节阈值 : `SMALL` 16个基B, `MEDIUM` 512基贝, `LARGE` 4个小米B |
| `uploadFrequency` | `'RARE' | 'NORMAL' | 'FREQUENT'` | 没有 | `'NORMAL'` | 等待批次的上传频率和事件累积的窗口: `RARE` 30岁, `NORMAL` 10岁, `FREQUENT` 5号 |
| `defaultPrivacyLevel` | `'mask' | 'allow' | 'mask-user-input'` | 没有 | `'mask'` | 渲染器会话重放的默认隐私级别 |
| `allowedRendererHosts` | `string[]` | 对 | —— 说 | 允许用于渲染器桥的主机名( 需要; 见下表) |
| `beforeSendRum` | `RumBeforeSend` | 没有 | —— 说 | 修改或丢弃已完全组装的主流程和渲染器 RUM 事件 |

#### `traceSamplingRules`

规则按照根痕量开始时的顺序进行评估. 第一个匹配规则决定了痕迹的百分比 保存; 未匹配的痕迹使用 `traceSampleRate`在一个抽样的RUM会话中,每个根迹都是独立的抽样, 这样会话既可以包含保存的痕迹,也可以包含被拒绝的痕迹. 模式是小写不敏感,孩子会继承 根决定,微量上下文从不从无样本的 RUM 会话中被传播出来. 对于样本中被拒绝的痕迹 电子会议 `net` 请求省略跟踪头,而全局 `fetch` 财务报告和审定财务报表 `node:http` 传播被拒绝的样本 下游的决定会继承它 一个被拒绝的 HTTP 追踪仍然产生一个没有链接的 RUM 资源 .

| 密钥 | 需求 | 目的 |
| --- | --- | --- |
| `sampleRate` | 对 | 要保存的匹配痕迹的百分比 `0` 改为 `100` |
| `name` | 没有 | 匹配根跨操作名称, 例如 `http.request` |
| `resource` | 没有 | 匹配根横跨资源, 如 HTTP 方法 |
| `tags` | 没有 | 按名称和值匹配根宽标记; 每个配置的标记必须匹配 |

```ts
await init({
  // ...
  traceSamplingRules: [{ tags: { 'http.url': '*/health' }, sampleRate: 0 }],
});
```

#### `allowedRendererHosts` 数值

可能需要使用 DatadogEvent Bridge 的渲染器来源列表 。 由渲染器处理的控件通过主要过程发送事件;其他渲染器的浏览器SDK单独运行.

| 数值 | 允许 |
| --- | --- |
| `['example.com']` | 打开 `example.com` 和任何子域 |
| `['*.example.com']` | 仅包含 `example.com` |
| `['myapp']` | 自定义带有主机名的 protocol 渲染器 `myapp` (例如:. `app://myapp/index.html`(中文(简体) ) |
| `['file://']` | 全体 `file://` 渲染器( 无法进行路径级过滤 ) `file://`(中文(简体) ) |
| `['*']` | 所有渲染器包括: `file://` |
| `[]` | 任何渲染器都无法桥接 |

> **自定义协议 :** 类似自定义协议 `app://` 或者说 `your-scheme://`,使用主机名组件(介于 `://` 和第一个 `/`) (中文(简体) ). 譬如说, `app://myapp/index.html` 匹配主机 `myapp`。 。 。 .

## 常见问题

### @datadog/electron-sdk 是什么？

用于电子应用的数据Dog SDK

### 如何安装 @datadog/electron-sdk？

在项目目录运行 npm install @datadog/electron-sdk，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：electron（\>=39）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @datadog/electron-sdk 支持 TypeScript 吗？

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

### @datadog/electron-sdk 支持 ESM 还是 CommonJS？

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

### @datadog/electron-sdk 可以商用吗？

@datadog/electron-sdk 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @datadog/electron-sdk 的下载量有多少？

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

### @datadog/electron-sdk 还在维护吗？

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