隐私与权限说明¶

隐私规则应在数据进入 RUM 或 Log 队列前生效。C# 与 Native C/C++ 都支持 URL Query、HTTP 请求 Header 和响应 Header 脱敏，并可以通过通用 Modifier 处理业务敏感字段。

权限配置说明¶

Windows SDK 不会主动申请系统权限。应用需要保证进程可以访问配置的上报地址和缓存目录；WebView2、窗口句柄及网络组件仍遵循宿主应用自身的权限和安全策略。

默认行为¶

数据	.NET / C#	Native C/C++
URL Query	保留非敏感值，默认敏感参数替换为 `<redacted>`	相同
HTTP Header	默认采集并脱敏认证类 Header	相同
用户与自定义属性	可以通过 `DataModifier` 或 `LineDataModifier` 脱敏	相同
Log 内容与属性	可以通过 `DataModifier` 或 `LineDataModifier` 脱敏	相同
Trace Header	仅发送到 `ShouldTrace`/`should_trace` 允许的目标	相同

默认敏感 Query 名包括 token、access_token、refresh_token、client_secret、password、passwd、secret、api_key、apikey、auth 和 authorization。默认敏感 Header 名包括 Authorization、Cookie、Set-Cookie、Proxy-Authorization、X-Api-Key、X-Auth-Token 和 X-Datakit-Token。

统一处理顺序¶

RUM、Log、WebView 和 Native Browser Bridge 数据在写入磁盘缓存前使用相同的处理顺序：

DataModifier：逐个处理已有 Tag 和 Field；返回 null 或 Native 回调返回 0 时保留原值。
LineDataModifier：按 Measurement 查看整条数据，并更新已有字段；新增字段会被忽略。
HTTP 隐私规则：最后处理 URL Query、请求 Header 和响应 Header，避免自定义 Modifier 绕过配置的网络脱敏规则。
格式化并写入缓存。

Modifier 可能在多个采集线程并发执行，不应在回调中执行耗时操作。回调异常不会中断数据采集，对应字段保持原值。

隐私配置¶

.NET / C#Native C/C++

GuanceSdk.Init(new GuanceConfig
{
    DatawayUrl = "https://openway.guance.com",
    ClientToken = "<client-token>",
    RumAppId = "<rum-app-id>",
    DataModifier = (key, value) =>
    {
        return key switch
        {
            "user_email" => "<redacted>",
            "phone" => "<redacted>",
            _ => null
        };
    },
    LineDataModifier = (measurement, data) =>
    {
        if (measurement == "error" && data.ContainsKey("error_message"))
        {
            return new Dictionary<string, object?>
            {
                ["error_message"] = "<redacted-error>"
            };
        }
        return null;
    },
    Privacy = new RumPrivacyConfig
    {
        CaptureHttpHeaders = true,
        CaptureUrlQueryString = true,
        RedactAllUrlQueryValues = false,
        RedactedValue = "<redacted>",
        RedactedHeaderNames = new[]
        {
            "Authorization",
            "Cookie",
            "Set-Cookie",
            "X-Api-Key"
        },
        RedactedQueryParameterNames = new[]
        {
            "token",
            "password",
            "secret"
        }
    }
});

参数	默认值	说明
`CaptureHttpHeaders`	`true`	是否记录脱敏后的请求和响应 Header。
`CaptureUrlQueryString`	`true`	是否保留 URL Query。关闭后移除整个 Query。
`RedactAllUrlQueryValues`	`false`	是否隐藏全部 Query 值。
`RedactedValue`	`<redacted>`	脱敏替换文本。
`RedactedHeaderNames`	认证类 Header	Header 名单，不区分大小写。
`RedactedQueryParameterNames`	敏感参数名单	Query 参数名单，不区分大小写。

DataModifier 和 LineDataModifier 都是可选配置。如果只需要默认 HTTP 脱敏，只配置 Privacy 即可。

#include <cstring>

static int modify_data(
    const char* key,
    const guance_data_value*,
    guance_data_value* replacement,
    void*) {
    if (std::strcmp(key, "user_email") != 0) {
        return 0;
    }
    replacement->type = GUANCE_DATA_VALUE_STRING;
    replacement->value.string_value = "<redacted>";
    return 1;
}

static void modify_line(
    const char* measurement,
    guance_data_item* data,
    uint32_t data_count,
    void*) {
    if (std::strcmp(measurement, "error") != 0) {
        return;
    }
    for (uint32_t index = 0; index < data_count; ++index) {
        if (std::strcmp(data[index].key, "error_message") == 0) {
            data[index].value.type = GUANCE_DATA_VALUE_STRING;
            data[index].value.value.string_value = "<redacted-error>";
        }
    }
}

guance_sdk_config sdk_config;
guance_sdk_config_init(&sdk_config);
sdk_config.dataway_url = "https://openway.guance.com";
sdk_config.client_token = "<client-token>";
sdk_config.rum_app_id = "<rum-app-id>";
guance_sdk_handle rum = guance_sdk_init(&sdk_config);

guance_data_modifier_config modifiers;
guance_data_modifier_config_init(&modifiers);
modifiers.data_modifier = modify_data;
modifiers.line_data_modifier = modify_line;
guance_configure_data_modifiers(rum, &modifiers);

const char* redacted_query_names[] = {
    "token",
    "password",
    "secret"
};
const char* redacted_header_names[] = {
    "Authorization",
    "Cookie",
    "Set-Cookie",
    "X-Api-Key"
};

guance_rum_resource_collection_config privacy;
guance_rum_resource_collection_config_init(&privacy);
privacy.capture_http_headers = 1;
privacy.capture_url_query = 1;
privacy.redact_all_url_query_values = 0;
privacy.redacted_value = "<redacted>";
privacy.redacted_query_parameter_names = redacted_query_names;
privacy.redacted_query_parameter_name_count = 3;
privacy.redacted_header_names = redacted_header_names;
privacy.redacted_header_name_count = 4;

guance_rum_configure_resource_collection(rum, &privacy);

所有 Native 配置结构都必须先调用对应的 *_init()。HTTP 隐私配置会复制 Header 和 Query 名单；Modifier 会保留函数指针与 user_data，它们必须在重新配置或 guance_sdk_shutdown() 前保持有效。Modifier 可能并发执行，且不能重新调用同一个 SDK Handle。

数据脱敏¶

关闭网络数据采集¶

.NET / C#Native C/C++

GuanceSdk.EnableAutomaticInstrumentation(new AutomaticInstrumentationOptions
{
    EnableHttpClient = false,
    EnableWebView = false
});

只关闭 Header 或 Query：

Privacy = new RumPrivacyConfig
{
    CaptureHttpHeaders = false,
    CaptureUrlQueryString = false
}

guance_rum_resource_collection_config resource_config;
guance_rum_resource_collection_config_init(&resource_config);
resource_config.enabled = 0;
guance_rum_configure_resource_collection(rum, &resource_config);

目标过滤¶

Native Resource 可以通过 should_collect 过滤采集目标；C# 应在业务 Handler 或手动 Resource 边界执行同等过滤。Trace Header 必须通过 Trace 配置中的目标白名单限制到可信服务。

用户、Log 和自定义字段¶

不要写入密码、Token、身份证件、支付信息或完整认证 Header。
用户 ID 应使用业务允许的稳定标识或哈希值。
Log 内容与属性不会自动理解业务敏感字段，应通过 Modifier 或在 AddLog() 前完成脱敏。
自定义属性不能覆盖 SDK 保留字段；冲突字段会被忽略。

Session Replay 隐私¶

实验性能力

Session Replay 默认关闭，可以显式开启验证，但仍为实验性能力。开启前必须确认默认策略和元素级覆盖满足业务隐私要求。

Session Replay 的全局隐私级别、元素级覆盖及 WebView2/Electron 隐私边界已统一整理到 Windows 会话重放隐私配置和隐私覆盖。