Rumable SDK 来源与配置¶
本页说明 Rumable 如何注入、加载和初始化 SDK。无需手写配置的方式见一键接入；手动配置时跳到四种接入方式的完整示例；首次安装见安装与接入，版本更新与回滚见运维说明。
注入方式与时序¶
Rumable 在 Web 服务器返回的标准 <head> 后加入外部脚本，不修改业务源文件。来源与加载方式互相独立：
| 来源与方式 | 下载位置 | 执行顺序 |
|---|---|---|
| 同域 + 异步，默认 | 安装包内置 SDK，由网站同域托管 | 异步加载初始化脚本，再动态异步下载 SDK，完成后初始化 |
| 同域 + 同步 | 安装包内置 SDK，由网站同域托管 | 先执行 SDK，再执行初始化脚本，然后继续解析页面 |
| CDN + 异步 | SDK 来自官方或自建 CDN，初始化脚本同域 | 初始化脚本异步下载 CDN SDK，完成后初始化 |
| CDN + 同步 | SDK 来自官方或自建 CDN，初始化脚本同域 | 先执行 CDN SDK，再执行初始化脚本，然后继续解析页面 |
同域资源位于网站的 __rumable__/<站点ID>/ 下，文件名包含内容摘要。选择同域仅改变 SDK 的下载位置，数据仍发往配置的上报端。
异步脚本下载不阻塞 HTML 解析，但初始化前的错误、请求和交互可能无法采集。同步方式使用两个不带 async、defer 的普通外部脚本，便于在后续业务脚本前完成初始化；网络慢或 CDN 故障会延迟后续页面解析和首屏。
同步不能保证捕获 SDK 加载失败或初始化之前的全部事件。SDK 加载失败不会自动切换到同域副本；同步模式仍需等待浏览器完成请求或判定失败。两种方式都不自动放宽 CSP。
source 和 loading 是什么意思¶
source 表示 SDK 从哪里下载，loading 表示 SDK 如何加载。两项独立选择：
| 配置项 | 填写值 | 中文含义 |
|---|---|---|
source |
"bundled" |
使用安装包内置的 SDK，由你的网站同域提供 |
source |
"cdn" |
从 url 指定的 CDN 地址下载 SDK |
loading |
"async" |
异步：页面继续解析，SDK 加载完成后开始采集 |
loading |
"sync" |
同步：先加载 SDK 并初始化，再继续解析后面的页面 |
url |
完整 HTTPS 脚本地址 | 只在使用 CDN 时填写 |
integrity |
false / true |
是否启用浏览器 SRI 完整性校验；默认 false，CDN 开启前需满足下方 CORS 和摘要要求 |
不写 loading 就使用异步，也可以显式填写 loading = "async"。下面的示例均写出加载方式，便于直接对照。[sites.sdk] 是 TOML 中放置这些选项的配置段名称，不是另外一个需要填写的参数。
在配置页中选择并一键接入¶
推荐先使用一键接入流程：在页面填写应用参数、选择 SDK 方式，再复制生成的命令到服务器执行。无需手写下面的 TOML。配置页在“选择 SDK 来源与加载方式”中提供两个下拉框：
| 想要的效果 | “SDK 来源”选什么 | “加载方式”选什么 | CDN 地址 |
|---|---|---|---|
| 网站同域 + 异步 | 网站同域（默认） | 异步（默认） | 不填 |
| 网站同域 + 同步 | 网站同域（默认） | 同步 | 不填 |
| CDN + 异步 | CDN | 异步（默认） | 填写 SDK 的 HTTPS 地址 |
| CDN + 同步 | CDN | 同步 | 填写 SDK 的 HTTPS 地址 |
例如要用官方 CDN 同步加载，就选择“CDN”和“同步”，CDN 地址填写 https://static.guance.com/browser-sdk/v3/dataflux-rum.js。确认右侧摘要后，读取发布版本、下载 TOML，再按页面生成的命令执行。
一键接入支持上述四种组合，也支持自动发现网站时选择 CDN 和同步加载。
已安装 CLI 的站点¶
首次接入直接使用 latest 配置页生成的命令。已有站点如需修改 SDK 来源或加载方式，保留原配置、站点 ID 和状态目录，按配置更新与升级重新应用。下载 TOML 或刷新配置页不会自动更新服务器上的 CLI 和 SDK。
四种接入方式的完整示例¶
以下四个代码块都是 Linux / Nginx 的完整配置文件，每次只选择一个，保存为 /etc/rumable/website.toml；不要把四个示例拼到同一文件里。已有站点先备份原 TOML，只修改原 [sites.sdk] 段，保留原站点 ID、路径、采样等设置。
首次接入时替换以下值：
| 示例值 | 替换为什么 |
|---|---|
website |
本次接入的站点 ID；后续更新保持不变 |
https://www.example.com/ |
你的网站地址；路径以 / 结尾 |
/usr/sbin/nginx |
实际 Nginx 可执行文件路径 |
YOUR_APPLICATION_ID |
Web 应用的应用 ID |
https://openway.example.com |
控制台提供的 OpenWay 地址，只填协议、主机和可选端口 |
YOUR_CLIENT_TOKEN |
对应的浏览器接入令牌 |
service、env、version 按业务填写；这里的 version 是业务应用版本，不是 SDK 版本。示例启用全部会话采样、关闭回放，完成验收后再调整。
示例 1：网站同域 + 异步¶
默认方式。SDK 由你的网站同域提供，页面不等待它加载完成。
schemaVersion = 1
[[sites]]
id = "website"
publicURL = "https://www.example.com/"
includePaths = ["/"]
excludePaths = ["/downloads/"]
probePaths = ["/"]
[sites.nginx]
binary = "/usr/sbin/nginx"
attachmentReviewed = false
[sites.rum]
applicationId = "YOUR_APPLICATION_ID"
site = "https://openway.example.com"
clientToken = "YOUR_CLIENT_TOKEN"
service = "website"
env = "production"
version = "1.0.0"
sessionSampleRate = 100
sessionReplayEnabled = false
defaultPrivacyLevel = "mask"
[sites.sdk]
source = "bundled" # 网站同域
loading = "async" # 异步加载，不等待 SDK 下载完成
示例 2：网站同域 + 同步¶
SDK 由你的网站同域提供，先初始化再继续解析页面。
schemaVersion = 1
[[sites]]
id = "website"
publicURL = "https://www.example.com/"
includePaths = ["/"]
excludePaths = ["/downloads/"]
probePaths = ["/"]
[sites.nginx]
binary = "/usr/sbin/nginx"
attachmentReviewed = false
[sites.rum]
applicationId = "YOUR_APPLICATION_ID"
site = "https://openway.example.com"
clientToken = "YOUR_CLIENT_TOKEN"
service = "website"
env = "production"
version = "1.0.0"
sessionSampleRate = 100
sessionReplayEnabled = false
defaultPrivacyLevel = "mask"
[sites.sdk]
source = "bundled" # 网站同域
loading = "sync" # 等待 SDK 加载并初始化后再继续解析页面
示例 3：CDN + 异步¶
浏览器异步下载指定 CDN 的 SDK，初始化脚本仍由网站同域提供。
schemaVersion = 1
[[sites]]
id = "website"
publicURL = "https://www.example.com/"
includePaths = ["/"]
excludePaths = ["/downloads/"]
probePaths = ["/"]
[sites.nginx]
binary = "/usr/sbin/nginx"
attachmentReviewed = false
[sites.rum]
applicationId = "YOUR_APPLICATION_ID"
site = "https://openway.example.com"
clientToken = "YOUR_CLIENT_TOKEN"
service = "website"
env = "production"
version = "1.0.0"
sessionSampleRate = 100
sessionReplayEnabled = false
defaultPrivacyLevel = "mask"
[sites.sdk]
source = "cdn" # 从 CDN 下载
url = "https://static.guance.com/browser-sdk/v3/dataflux-rum.js"
integrity = false
loading = "async" # 异步加载，不等待 SDK 下载完成
示例 4：CDN + 同步¶
先加载 CDN SDK、完成初始化，再继续解析页面。
schemaVersion = 1
[[sites]]
id = "website"
publicURL = "https://www.example.com/"
includePaths = ["/"]
excludePaths = ["/downloads/"]
probePaths = ["/"]
[sites.nginx]
binary = "/usr/sbin/nginx"
attachmentReviewed = false
[sites.rum]
applicationId = "YOUR_APPLICATION_ID"
site = "https://openway.example.com"
clientToken = "YOUR_CLIENT_TOKEN"
service = "website"
env = "production"
version = "1.0.0"
sessionSampleRate = 100
sessionReplayEnabled = false
defaultPrivacyLevel = "mask"
[sites.sdk]
source = "cdn" # 从 CDN 下载
url = "https://static.guance.com/browser-sdk/v3/dataflux-rum.js"
integrity = false
loading = "sync" # 等待 SDK 加载并初始化后再继续解析页面
IIS 和 DataKit 如何使用这些示例¶
IIS 使用同样的 [sites.sdk] 配置。将选中示例中的整个 [sites.nginx] 段替换为下面这一段，其余字段保留：
site 改成实际 IIS 站点名；allowCompressionChanges=true 表示允许关闭该应用的 IIS 静态和动态压缩；停用时恢复原设置。子应用 /shop 对应 publicURL=https://www.example.com/shop/，注入和验收路径也应使用 /shop/ 前缀。
使用 DataKit 上报时，在 [sites.rum] 中删除 site 和 clientToken，改为 datakitOrigin = "https://datakit.example.com"，并替换成真实地址。两种上报方式互斥，不追加 /v1/write/rum。
保存后如何应用¶
首次接入 Nginx 时，使用匹配版本的实际 CLI 路径执行：
这里的 rumable 代表已安装的 CLI；如果未加入 PATH，替换为它的绝对路径。确认拟修改的 Nginx 挂接后再应用，并检查浏览器执行和真实数据入库。已接入站点保留原状态目录，修改配置后重新执行 enable。
Windows 的首次接入和两种平台的验收见安装说明，已接入站点修改配置见运维说明。
CDN 地址、摘要与 SRI¶
- URL 必须是完整 HTTPS 脚本地址，不含账号密码、查询参数或片段。
- 自建 CDN 需提供与所选安装包完全相同的 SDK 字节。启用和探测会检查内容摘要、JavaScript MIME、普通和 gzip 响应。
- 浏览器 CSP 需允许实际 CDN 地址；选择 CDN 不会让初始化脚本离开网站同域。
- 跨域 SRI 需要 CDN 返回允许站点 Origin 或
*的Access-Control-Allow-Origin。当前官方 v3 地址默认不启用 SRI；开启前以实际响应头和安装检查为准。 - 官方 v3 为可变地址，探测时摘要匹配不锁定未来内容。若需固定版本，使用同域模式或维护不可变的自建 CDN 文件。
- 使用 bundled 时不要填写
url或开启integrity，否则校验会拒绝。
自动发现配置¶
自动发现是让工具扫描服务器已有的网站，再让你选择接入目标，省去手填网站地址和 Nginx/IIS 目标的步骤。它使用 server、[rum]、[sdk]，与包含 [[sites]] 的完整配置是两种格式。
以下都是完整的自动发现配置，每次只选一个，保存为 /etc/rumable/discovery.toml；替换应用 ID、OpenWay 地址和令牌。它们只能交给 setup --discover，不能直接交给 enable。
同域异步，使用默认行为，不写 SDK 配置段：
schemaVersion = 1
server = "nginx"
[rum]
applicationId = "YOUR_APPLICATION_ID"
site = "https://openway.example.com"
clientToken = "YOUR_CLIENT_TOKEN"
sessionReplayEnabled = false
CDN 同步，指定 SDK 地址和加载方式：
schemaVersion = 1
server = "nginx"
[rum]
applicationId = "YOUR_APPLICATION_ID"
site = "https://openway.example.com"
clientToken = "YOUR_CLIENT_TOKEN"
sessionReplayEnabled = false
[sdk]
source = "cdn"
url = "https://static.guance.com/browser-sdk/v3/dataflux-rum.js"
loading = "sync"
integrity = false
Windows 将 server 改为 "iis"，并按实际授权在 [rum] 之前设置顶层 allowCompressionChanges = true。SDK 参数含义与完整配置相同，但配置段名称是 [sdk]，不能写成 [sites.sdk]。
Nginx 通过实际安装的 CLI 执行，终端选择站点后会打印接入标识：
Windows 在管理员终端使用实际 exe、配置文件和状态目录执行 setup --discover。后续继续使用原站点 ID、目标和状态目录；不要用另一个任意 ID 接管同一部署。
路径、采样与回放¶
includePaths 与 excludePaths 按区分大小写的前缀匹配，排除优先；probePaths 必须位于注入范围内，并直接返回可验收的 HTML。路径决定服务器是否改写该页面，不等于排除 SDK 的 Fetch/XHR 请求，也不会在 SPA 切换路由时重新判断注入。
回放默认关闭。在完整配置已有的 [sites.rum] 中调整以下字段，而不是重复增加该表：
sessionSampleRate = 100
sessionReplayEnabled = true
sessionReplaySampleRate = 20
sessionReplayOnErrorSampleRate = 0
defaultPrivacyLevel = "mask"
回放依赖 RUM 会话采样，改变采样率后用新会话验收。回放、请求压缩和远程配置可能需要 Worker；默认 Blob Worker 需要 CSP 允许 blob:，外置 Worker 由用户同域托管并保持版本匹配。
详细采样含义见采样配置。setUser、手动 startView、自定义事件和函数回调仍需要业务代码；Rumable 的静态配置不能自动替代这些调用。「应用版本」是业务标签，「SDK 远程配置」调整采集参数，两者都不升级 SDK 文件。
配置页或 CLI 提示不支持所选方式¶
打开latest 配置页，重新读取发布版本并生成安装命令。已安装的 CLI 如果提示不认识 loading 或 [sdk]，按升级步骤更新 CLI，再应用原站点配置。升级时保留原站点 ID、目标和状态目录。