# YLSensitiveReport

**Repository Path**: sweetzz/YLSensitiveReport

## Basic Information

- **Project Name**: YLSensitiveReport
- **Description**: No description available
- **Primary Language**: Swift
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-03
- **Last Updated**: 2025-10-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README


# YLSensitiveReport

YLSensitiveReport 是一个用于 iOS 的轻量级敏感事件收集与上报 SDK，支持设备状态、充电/低电、屏幕锁定、通话、网络、蓝牙与流量等多种监控能力，并提供异步回调与可配置选项。

## 特性

- 事件驱动：通过委托回调接收检测到的敏感事件。
- 可配置：按需开启或关闭各类监控模块（充电、屏幕锁定、低电量、网络、通话、蓝牙、流量）。
- 支持快速启动与单项启动配置。 
- 提供调试日志开关与低电阈值自定义。
- 包含资源文件（Device.json / deviceInfo.json）与脚本（SFRefreshDevice.sh）。

## 安装

通过 CocoaPods 安装（Podspec 已包含 Core 与 Scripts 子规格）：

1. 在你的 `Podfile` 中添加：

```ruby
pod 'YLSensitiveReport', '~> 1.0.0'
```

2. 运行：

```bash
pod install
```

## 使用说明

主要入口类为 `YLSensitiveReport`，配置由 `YLSensitiveReportConfig` 提供，并通过 `YLSensitiveReportDelegate` 接收事件与状态变化回调。

### 基本契约

- 输入：SDK 根据 `YLSensitiveReportConfig` 启用或禁用各个监控模块。
- 输出：通过 `YLSensitiveReportDelegate.sensitiveReport(didDetectEvent:)` 回调传递 `YLSensitiveEvent`。
- 错误模式：如果配置不合法或重复启动，会抛出 `YLSensitiveReportError`（如 `.alreadyStarted`, `.configurationError`）。

### 事件类型

`YLSensitiveEventType` 包含的事件：

- `chargingConnected`：检测到充电器连接
- `chargingDisconnected`：检测到充电器断开
- `screenLocked`：锁屏
- `screenUnlocked`：解锁
- `lowBattery(level: Float)`：低电量，携带电量百分比（0.0 - 1.0）
- `callStarted(isIncoming: Bool)`：通话开始，isIncoming 表示是否为来电
- `callEnded(isIncoming: Bool, startTime: TimeInterval, duration: TimeInterval)`：通话结束
- `networkChanged(type: YLNetworkType)`：网络类型变化
- `bluetoothChanged(isOn: Bool)`：蓝牙开关状态变化
- `trafficChanged(model: YLDeviceInfoModel)`：流量/设备信息变化

每个事件会被封装为 `YLSensitiveEvent`，包含 `type: YLSensitiveEventType`、`timestamp: Date` 与可选的 `extInfo` 字典。

### 初始化与启动

实现 `YLSensitiveReportDelegate` 来接收事件：

```swift
class MyDelegate: YLSensitiveReportDelegate {
	func sensitiveReport(didDetectEvent event: YLSensitiveEvent) {
		// 在这里处理事件，例如上传、埋点或本地记录
		print("Detected event: \(event.type) at \(event.timestamp)")
	}
}

let delegate = MyDelegate()

do {
	// 使用默认配置快速启动
	try YLSensitiveReport.shared.quickStart(delegate: delegate)
} catch {
	print("Failed to start YLSensitiveReport: \(error.localizedDescription)")
}
```

或者使用自定义配置：

```swift
let config = YLSensitiveReportConfig.defaultConfig()
config.isBluetoothMonitorEnabled = false // 按需关闭蓝牙监控
config.isDebugLogEnabled = true

do {
	try YLSensitiveReport.shared.startReporting(with: config, delegate: delegate)
} catch {
	// 处理配置错误或重复启动错误
}
```

### 快速启动单项监控

SDK 提供多种快捷启动方法：

- `startChargingMonitorOnly(delegate:)`
- `startScreenLockMonitorOnly(delegate:)`
- `startNetworkMonitorOnly(delegate:)`
- `startLowBatteryMonitorOnly(delegate:)`
- `startCallMonitorOnly(delegate:)`
- `startBluetoothMonitorOnly(delegate:)`
- `startTrafficMonitorOnly(delegate:)`

示例：

```swift
do {
	try YLSensitiveReport.shared.startNetworkMonitorOnly(delegate: delegate)
} catch {
	print("start failed: \(error)")
}
```

### 停止与更新配置

停止 SDK：

```swift
YLSensitiveReport.shared.stopReporting()
```

更新配置（请注意：更新后通常需要重启 SDK 才能生效）：

```swift
do {
	var newConfig = YLSensitiveReportConfig.defaultConfig()
	newConfig.isTrafficMonitorEnabled = false
	try YLSensitiveReport.shared.updateConfig(newConfig)
} catch {
	print("Invalid config: \(error)")
}
```

### 配置验证与错误

调用 `startReporting` 或 `updateConfig` 时，SDK 会调用 `YLSensitiveReportConfig.validate()`。常见错误：

- `YLSensitiveReportError.alreadyStarted`：已启动再调用启动方法
- `YLSensitiveReportError.configurationError(String)`：配置不合法，例如所有监控均关闭，或低电阈值无效，或缺少 Info.plist 所需的蓝牙权限说明。

请在捕获错误后适当处理（提示、退回默认配置或上报日志）。

## Info.plist 权限（蓝牙）

如果启用了蓝牙监控（`isBluetoothMonitorEnabled = true`），请在应用的 `Info.plist` 中添加以下其中一项描述字符串：

- `NSBluetoothAlwaysUsageDescription`
- `NSBluetoothPeripheralUsageDescription`

用于向用户说明为何需要访问蓝牙。

## 资源与脚本

SDK 的资源文件位于 `Sources/YLSensitiveReport/Resources/`，包括：

- `Device.json`、`deviceInfo.json`：设备相关数据（用于内部设备信息/流量统计）
- `SFRefreshDevice.sh`：脚本，用于在 pod 安装或编译前更新或处理设备数据库（Podspec 中将其设置为 `script_phase` 在编译前执行）。

如果你以源码方式集成，请确保脚本具有可执行权限（Pod 安装脚本会自动尝试设置）。

## 开发与调试

在开发阶段可以开启调试日志：

```swift
let config = YLSensitiveReportConfig.defaultConfig()
config.isDebugLogEnabled = true
config.logPrefix = "[MyApp:YLSensitive]"
```

调试日志会通过 `print` 输出，包含 `logPrefix` 前缀。

## 版本信息

当前 SDK 版本：1.0.0（请以 Podspec 或包管理器中的版本为准）

## 常见问题

- Q: SDK 会自动上传数据到我的服务器吗？
  A: SDK 本身只负责检测并通过 `YLSensitiveReportDelegate` 回调事件，具体上传或存储逻辑应在委托中实现，以便适配你的隐私策略与上传流程。

- Q: 如果我只想监听屏幕锁定事件，如何做？
  A: 使用 `startScreenLockMonitorOnly(delegate:)` 或在配置中仅开启 `isScreenLockMonitorEnabled` 并调用 `startReporting`。

## 联系与贡献

项目主页：https://gitee.com/sweetzz/YLSensitiveReport

欢迎提交 issue 与 PR。

---

文档由代码注释与接口签名自动提取，若需更多示例或扩展文档（例如 Objective-C 使用示例、上报流程示例、单元测试示例），我可以继续添加。