帮你快速理解、总结文档立即下载
文档中心>腾讯云可观测平台>用户体验监控>接入指南>Electron SDK 接入指引>SDK 集成

SDK 集成

最近更新时间：2026-09-30 17:29:02
本文档已由 AI 辅助审校
我的收藏

本页目录：

用户体验监控 Electron SDK 通过 npm 安装，采用 main + renderer 两步接入。只需安装一个包，renderer 所需的 Web SDK 已内置。

前提条件

Electron >=23。
项目使用 main / renderer 分进程结构，且能分别构建两端入口文件。
若使用 TypeScript，建议开启 esModuleInterop。

安装

npm install tdem-electron-sdk --save
注意：
包名统一为 tdem-electron-sdk，不带 @tencent 前缀。
依赖 tdem-node-sdk 会随包自动安装，不要单独在业务里安装或 init 它。
只需安装这一个包：renderer 需要的 Web SDK 已内置，无需应用安装或声明。

两个进程入口

SDK 只公开两个子路径入口，请按进程分别引入：
入口
进程
典型文件
tdem-electron-sdk/main
主进程
main.ts / index.ts（主入口）
tdem-electron-sdk/renderer
渲染进程
渲染层入口（如 renderer.ts）
// 主进程
import { init } from 'tdem-electron-sdk/main';

// 渲染进程
import { init } from 'tdem-electron-sdk/renderer';
注意：
两端不要混用入口。在主进程引入 tdem-electron-sdk/renderer（或反之）会导致 bootstrap 获取失败、SDK 拒绝初始化。

初始化时序（关键约束）

必须在创建任何 BrowserWindow 或自定义 Session 之前完成 main 初始化：
1. main 进程启动，调用 init()。
2. SDK 注入内置 preload 并注册 IPC 代理。
3. 之后才创建 BrowserWindow。
4. renderer 加载后调用 init()。
// main.ts —— 先初始化，再建窗口
import { app, BrowserWindow } from 'electron';
import { init } from 'tdem-electron-sdk/main';

const tdem = init({
  id: 'project-id',
  url: 'https://dem.rumt-zh.com',
});

app.whenReady().then(() => {
  const window = new BrowserWindow({
    webPreferences: {
      contextIsolation: true,
      nodeIntegration: false,
    },
  });
  // ...
});
注意：
顺序颠倒会导致 SDK 的自带 preload 未注入到已存在的 Session 上，renderer 侧 init() 会直接拒绝（不会降级为浏览器直传）。
renderer 侧入口的初始化方式与 main 不同：init() 返回 Promise，必须 await 取得 client 后再调用其方法；id / url / version 由 main 侧提供，renderer 不要重复传入。可选配置（如会话回放采样率）与完整参数说明见 SDK 初始化-操作步骤：
// renderer.ts —— 渲染进程入口
import { init } from 'tdem-electron-sdk/renderer';

const tdem = await init();

preload 注入机制

SDK 的自动注入依赖 Electron 23及以上版本，并按版本走两条实现路径：
Electron 35+：调用 session.registerPreloadScript() 注册 SDK 自带的 preload.cjs。
Electron 23 - 34：调用 session.getPreloads() 读取现有脚本列表，再用 setPreloads() 把 SDK preload 插到最前，从而保留业务已有的 preload。
同时监听 app 的 session-created 事件，对后续创建的自定义 partition 一并注入；若初始化时 app 已 ready，则立即补注入。因此：
不要在 new BrowserWindow() 里配置 TDEM 的 preload 路径，SDK 已自动接管。
业务自己的 webPreferences.preload 原样保留，Electron 会先执行 Session preload、再执行它，SDK 不会覆盖。
若业务自行调用 session.setPreloads() 覆盖完整列表，可能把 SDK preload 挤掉；此时 renderer 侧 init() 会直接拒绝（不会降级为浏览器直传），请改用追加方式或确保顺序。

上报域名

请根据项目所在地域选择对应的上报域名。不同站点的数据相互隔离，跨站填写会导致数据无法入库。
站点
上报域名
国内站
https://dem.rumt-zh.com
新加坡站
https://dem.rumt-sg.com
美国站
https://dem.rumt-us.com
接入时填写站点根地址即可，无需拼接路径，SDK 会自行拼接具体协议端点。

打包注意事项

若启用了 Node 子进程注入（把 sidecar / CLI 纳入同一 TDEM 会话，nodeInjection: true，默认关闭，详见 SDK 初始化-Node 子进程注入），打包时必须把 Node SDK 留在 asar 外，否则预加载无法解析真实文件。以 electron-builder 为例：
{
  "asarUnpack": ["**/node_modules/tdem-node-sdk/**"]
}

中国站