Windows 会话重放¶
实验性功能
Windows SDK 的 Session Replay 默认关闭，可以显式开启和验证，但尚未进入稳定发布范围。接入前请自行评估目标应用的兼容性、隐私、性能和数据量；请勿将当前行为作为稳定兼容承诺。
支持范围¶
WPF、WinForms、WinUI 3、WebView2、Electron 和 Native C/C++ 应用均可显式开启验证。不同 UI 框架、跨域 Frame、Canvas、自定义渲染内容和媒体播放控件的回放效果需要在目标应用中单独验证。
启用会话重放¶
初始化 SDK 时显式将 SessionReplay.Enabled 设为 true。下面示例使用公网 DataWay；使用本地环境部署（DataKit）时，将 DatawayUrl 和 ClientToken 替换为 DatakitUrl。
using Guance.Windows;
GuanceSdk.Init(new GuanceConfig
{
DatawayUrl = "https://openway.<your-domain>",
ClientToken = "<client-token>",
RumAppId = "<rum-app-id>",
ServiceName = "desktop-client",
Env = "prod",
Version = "1.0.0",
SessionReplay = new RumSessionReplayConfig
{
Enabled = true,
SampleRate = 1.0,
OnErrorSampleRate = 0.0,
TextAndInputPrivacy = SessionReplayTextAndInputPrivacy.MaskAll,
TouchPrivacy = SessionReplayTouchPrivacy.Show,
ImagePrivacy = SessionReplayImagePrivacy.MaskAll
}
});
Native C/C++ 应用在初始化前设置对应字段：
#include "guance_sdk.h"
guance_sdk_config config;
guance_sdk_config_init(&config);
config.session_replay_enabled = 1;
config.session_replay_sample_rate = 1.0;
config.session_replay_on_error_sample_rate = 0.0;
同时填写 DataWay 或 DataKit、RUM 应用 ID、服务名、环境和应用版本等初始化必填项后，再调用 guance_sdk_init()。Native SDK 还需要按窗口生命周期注册回放窗口；WebView2 和 Electron 页面记录通过各自的 Native Bridge 写入同一会话。
隐私配置¶
会话重放可能采集界面中的文本、输入、点击和图像信息。启用前应先在测试环境验证采集内容、数据量和上传行为，并确认全局配置与元素级覆盖满足业务隐私要求。
| 属性 | 类型 | 必须 | 含义 |
|---|---|---|---|
TextAndInputPrivacy |
SessionReplayTextAndInputPrivacy |
否 | 设置文本和输入内容的隐私级别。MaskSensitiveInputs 仅遮蔽敏感输入；MaskAllInputs 遮蔽所有输入内容；MaskAll 遮蔽所有文本和输入内容；Allow 不遮蔽文本和输入内容。默认 MaskAll。 |
TouchPrivacy |
SessionReplayTouchPrivacy |
否 | 设置指针和触控行为的隐私级别。Show 显示指针和触控行为；Hide 隐藏指针和触控行为。默认 Show。 |
ImagePrivacy |
SessionReplayImagePrivacy |
否 | 设置图片内容的隐私级别。MaskAll 遮蔽所有图片；MaskLargeOnly 遮蔽渲染面积超过阈值的图片；MaskNone 不主动遮蔽图片。默认 MaskAll。 |
建议默认使用文本、输入和图片脱敏等保守策略，并只在完成业务评估后放宽规则。对于账号、支付、身份凭证或其他敏感数据，应通过元素级隐私覆盖设置更严格的规则，或隐藏整个元素。
隐私覆盖¶
SDK 除了支持通过 RumSessionReplayConfig 配置全局隐私级别，还支持在视图级覆盖这些设置。以下元素级 API 适用于 .NET 的 WPF、WinForms 和 WinUI 3 控件。
视图级隐私覆盖：
- 支持覆盖文本和输入、触控以及图片的隐私级别
- 支持完全隐藏指定元素及其子元素
注意：
- 为了确保正确识别覆盖设置，应在元素生命周期中尽早应用
- 隐私覆盖会作用于元素及其子元素
- 文本、触控和图片隐私覆盖优先级：子元素 > 父元素 > 全局设置
- 隐藏设置会作用于整个元素树，子元素不能移除从父元素继承的隐藏设置
文本和输入覆盖¶
使用 GuanceSdk.SetSessionReplayTextAndInputPrivacy() 设置元素的文本和输入隐私级别。传入 null 可以移除当前元素的覆盖设置。
// 对指定元素设置文本和输入隐私覆盖
GuanceSdk.SetSessionReplayTextAndInputPrivacy(
passwordBox,
SessionReplayTextAndInputPrivacy.MaskAll);
// 移除指定元素的文本和输入隐私覆盖
GuanceSdk.SetSessionReplayTextAndInputPrivacy(passwordBox, null);
触控覆盖¶
使用 GuanceSdk.SetSessionReplayTouchPrivacy() 设置元素的指针和触控隐私级别。传入 null 可以移除当前元素的覆盖设置。
// 隐藏指定元素的指针和触控行为
GuanceSdk.SetSessionReplayTouchPrivacy(
paymentPanel,
SessionReplayTouchPrivacy.Hide);
// 移除指定元素的指针和触控隐私覆盖
GuanceSdk.SetSessionReplayTouchPrivacy(paymentPanel, null);
图片覆盖¶
使用 GuanceSdk.SetSessionReplayImagePrivacy() 设置元素的图片隐私级别。传入 null 可以移除当前元素的覆盖设置。
// 遮蔽指定元素中的所有图片
GuanceSdk.SetSessionReplayImagePrivacy(
identityImage,
SessionReplayImagePrivacy.MaskAll);
// 移除指定元素的图片隐私覆盖
GuanceSdk.SetSessionReplayImagePrivacy(identityImage, null);
隐藏元素覆盖¶
对于需要完全隐藏的敏感元素，使用 GuanceSdk.SetSessionReplayHidden() 进行设置。设置后，该元素在重放中显示为 Hidden 占位符，子元素不会被记录。
// 隐藏指定元素及其子元素
GuanceSdk.SetSessionReplayHidden(customerIdentityPanel, true);
// 移除指定元素的隐藏设置
GuanceSdk.SetSessionReplayHidden(customerIdentityPanel, false);
WebView2 和 Electron¶
WebView2 和 Electron 的 Browser collector 从原生 Bridge 的 getPrivacyLevel() 读取 allow、mask-user-input 或 mask。隐私级别必须由原生可信配置决定，Renderer 不能自行放宽。