Flutter SDK（未发布源码）

独立源码包 healthguard_flutter@0.3.0 位于主仓库 packages/sdk-flutter；尚未发布到 pub.dev。可在测试阶段使用 Git/path 依赖，正式接入固定审核过的 commit。

dependencies:
  healthguard_flutter:
    git:
      url: https://github.com/Claud-Lu/healthguard.git
      ref: 0aa9fad6ee1030b12e14566eae7658aec4fb00a0
      path: packages/sdk-flutter

import 'package:healthguard_flutter/healthguard_flutter.dart';
final healthGuard = HealthGuardClient(
  appKey: 'your-app-key',
  endpoint: 'https://collector.example.com/api/events/batch',
  release: 'your-app-version',
  environment: 'production',
);
await healthGuard.initialize();
dio.httpClientAdapter = HealthGuardIoHttpClientAdapter();
dio.interceptors.add(healthGuard.interceptor());
// On shutdown: healthGuard.dispose();

应用提供配置并挂载拦截器，监控不改变原 Dio 结果。主动取消不作为 HTTP 异常告警；已处理异常可调用 captureException，已处理 HTTP 失败可调用 captureHttpFailure。同一次失败只选一条自动或手动 HTTP 上报路径。

客户端串行持久化，队列最多 100 条、每批最多 50 条，默认 30 秒重试，保留原 ID、时间和版本。初始化后可调用 flushPending()；存储、transport 和 networkSnapshot 可注入适配器。

Android 插件最低 API 21，声明 INTERNET/ACCESS_NETWORK_STATE，不申请定位权限。存储依赖限制在仍支持 API 21 的版本范围；API 21/22 的 validated/VPN 字段不可用，API 23+ 可读默认网络，API 24+ 监听默认网络。其他平台原生网络状态目前不可用；Dio 只给出请求总耗时，分阶段耗时不伪造。

网络诊断与隐私适用于此 SDK。构建和模拟事件不能替代真机断网、重启补传、切网、VPN、旧 Android 安装或真实告警验收。

迁移已有集成

手动 captureHttpFailure 可传 occurredAt、eventEnvironment、deviceModel、deviceSystem 和 fingerprint，保留原故障时间、设备和聚合身份。networkDiagnostics 与 originalError 按白名单保留；被动快照 sampledAt 是采集时间，不伪装成原请求证据。

additionalContextKeys 可显式选择允许的标量业务字段，凭据键和嵌套业务载荷仍被拒绝。旧队列及安装身份通过 HealthGuardStorage 适配；先持久化新队列，再清旧存储。自定义 transport 必须确认完整批次 accepted 后才能成功返回。每次失败只使用一条自动或手动上报路径。

详细诊断统一到 SDK

SDK 0.2.1 提供 NetworkDiagnostics。应用只配置 allowedHosts、healthPath，并将 beginRequest、endRequest、collect 接到现有单条 HTTP 上报链路；请求编号、前后快照、网络事件、并发计数、最近成功响应和 DNS/TCP/TLS/健康检查均由 SDK 维护。

Android 的基础快照和详细事件共享一个带引用计数的监听器。迁移完成后可删除 App 原生监听及探测实现，保留 SDK 初始化、业务配置、已处理错误上报和旧队列迁移适配。无需同时挂载另一条自动 HTTP 上报拦截器。

主动探测默认关闭；显式域名白名单仅允许 HTTPS/443，健康检查路径不能包含域名、协议、查询或片段。不发送认证或业务参数，不跟随重定向，不放宽 TLS。每域单组探测、60秒缓存、分阶段和总时限控制流量，采样时间明确保留。结果不代表原业务请求的网络过程；主动取消不触发告警。

原请求连接等待（原生 IO，可选）

HealthGuardIoHttpClientAdapter 观测业务请求原有的 HttpClient.openUrl 和响应头返回，保留连接池、DNS、代理和 TLS 行为。已有自定义 HttpClient 或证书策略时，通过 createHttpClient/validateCertificate 传入原配置；不要覆盖业务必需的其他 adapter。原有 X-Request-ID 合法时复用，否则生成并发送新编号。

连接取得包含潜在连接池等待、DNS、TCP、TLS 或代理处理，未单独计量的子阶段显示不可用。响应头已收到不代表响应体已经读完。超时/取消后证据冻结，后续才建立的废弃连接被中止。

若业务已有唯一的手动 HTTP 上报，只配置 adapter，不重复挂自动上报拦截器。将 error.requestOptions.extra[healthGuardRequestTraceKey] 作为 context.requestTrace，并保留 context.originalError。SDK 仅保留白名单字段，不上传认证头、请求体、IP 或 URL 查询参数。独立探测具有自己的采样时间和缓存标记，不能当作原请求的网络阶段耗时。

设备标识与现场短码（0.3.0 源码，未发布）

Android 原生插件读取 Settings.Secure.ANDROID_ID，以 UTF-8 的版本前缀、作用域、应用包名、HealthGuard 项目 appKey 和 Android ID（NUL 分隔）生成 SHA-256；只把 hgd1_ 加 64 位十六进制脱敏值传给 Dart。原始 Android ID 不记录、不跨通道、不上报。appKey 用于命名空间而非加密密钥，脱敏标识仍应按假名数据处理，不能当认证凭证。

Android 8+ 作用域为 android_user_signing_key_app（设备/系统用户/签名，另加应用与项目隔离）；Android 5–7 为 android_user_app_legacy，底层没有 Android 8 的签名隔离，需验证厂商系统行为。同一作用域内正常重启与升级应保持一致，重装/清数据需在目标平板实测。恢复出厂、切换用户/工作资料、签名/包名/appKey 变化以及从 Android 8 之前升级后重装均可能改变标识；厂商实现也可能重复或重置。不能宣称永久唯一。

所有异常和失败请求共用 deviceId、deviceIdStatus、deviceIdSource、deviceIdScope、deviceInfo.model/system、release、sdkVersion。安装 anonymousId 和会话 sessionId 保持独立。原生查询最多等待 300ms；失败时 deviceIdStatus=unavailable，给出 deviceIdReason，省略 deviceId，显示“未获取”，不阻塞业务或改用随机设备标识。离线事件保留原标识和版本，不能用当前设备给历史补报回填。

await monitoring.initialize();
// 放进业务 App 现有的设置/调试导航：
Navigator.of(context).push(MaterialPageRoute(
  builder: (_) => HealthGuardDeviceDebugPage(client: monitoring),
));
// 也可读取 monitoring.deviceIdentity / monitoring.deviceShortCode。

短码为 HG- 加哈希前 12 位大写十六进制，仅供现场对照；可能碰撞，服务端必须使用完整标识/来源/作用域归集。邮件、Dashboard、AI 报告与调试页格式相同；邮件 App 版本取触发事件自身。先更新 Collector/Dashboard，再固定经审阅的 Git 提交更新 App；本页不代表 pub.dev 发布、服务器上线、APK 交付或实机验收。

实机需记录两台同型号平板、重启、正常升级、同签名重装及清数据前后的短码，包含 Android/API、包名、签名、App 版本和事件证据。当前目标平板未连接，以上生命周期实测待完成；不可擅自卸载或清空司机业务数据。标识失效时业务与上报继续的自动化检查不代替真实设备测试。

参考：Android ID、Android 8 行为变化。