---
name: ezopensdk-ios-skill
description: 萤石开放平台 EZOpenSDK iOS 端完整开发知识库。涵盖 SDK 接入配置、设备管理、实时预览/回放、语音对讲、设备配网、视频通话(ERTC)、数据模型、错误码排查、UI 最佳实践共 9 大模块，帮助三方开发者快速规范地接入萤石摄像头/NVR 等设备能力。
---

# EZOpenSDK iOS Skill

## 触发条件
当用户提到以下关键词时，应激活此 Skill：
- 萤石、EZVIZ、EZOpenSDK、萤石开放平台
- iOS、iPhone、iPad、Swift、Objective-C、ObjC
- 摄像头、监控、IPC、NVR、DVR
- 预览、直播、回放、录像、取流
- 对讲、全双工、半双工
- 配网、AP配网、声波配网、Smart配网、WiFi配置
- 视频通话、ERTC、视频会议
- 云台、PTZ、云存储、AI云存储
- 设备列表、设备信息、设备添加、设备删除
- 告警消息、布防、撤防
- 截图、录制、水印、清晰度
- EZPlayer、EZOpenSDK、EZDeviceInfo

## SDK 简介
萤石开放平台 EZOpenSDK（iOS）是萤石提供的移动端 SDK，支持对萤石摄像头、NVR 等设备进行预览、回放、对讲、配网、视频通话等操作。

### 核心类
| 类名 | 说明 |
|------|------|
| `EZOpenSDK` | SDK 主入口类，提供初始化、授权、设备管理、录像查询、配网、云台控制等 API |
| `EZGlobalSDK` | 海外版 SDK 主入口类，API 与 EZOpenSDK 基本一致 |
| `EZPlayer` | 播放器类，提供预览、回放、对讲、录制、截图、水印、电子放大等功能 |
| `EZDeviceInfo` | 设备信息对象，包含设备属性和能力集查询方法 |
| `EZCameraInfo` | 通道信息对象，包含通道号、清晰度、封面等属性 |

### 接入必读
- 仅支持真机调试，不支持模拟器
- 最低系统版本 iOS 13
- 支持架构：arm64
- 导入方式：CocoaPods（推荐）或手动导入静态库

## 功能模块索引

根据用户需求，参考对应的知识文件：

| 用户需求 | 参考文件 | 说明 |
|----------|----------|------|
| SDK 接入、初始化、授权、CocoaPods 配置、权限 | `ezopensdk-setup.md` | 从零开始接入 SDK 的全部前置工作 |
| 设备列表、设备信息、设备添加/删除/升级/存储管理 | `ezopensdk-device.md` | 设备管理相关的所有 API |
| 预览、回放、录制、截图、云台、清晰度、水印、电子放大、告警消息 | `ezopensdk-player.md` | EZPlayer 播放器相关的所有功能 |
| 对讲（全双工/半双工）、变声、音量回调 | `ezopensdk-talk.md` | 语音对讲相关功能 |
| 设备配网（AP/声波/Smart/接触式AP/网线） | `ezopensdk-wifi.md` | 设备网络配置 API 及错误码 |
| 视频通话、ERTC | `ezopensdk-ertc.md` | 视频通话相关功能 |
| 数据模型对象属性（EZAlarmInfo、EZCloudRecordFile 等） | `ezopensdk-models.md` | 所有对外开放对象的属性详解 |
| AI云存储、智能录像检索、AI对话查找录像 | `ezopensdk-ai-cloud-storage.md` | AI云存储视图集成（EZAICloudStorageView） |
| 错误码查询、常见问题排查 | `ezopensdk-errorcode.md` | 错误码表和 FAQ |

## 使用指引

1. 三方开发者首次接入时，按 `setup → device → player/talk/wifi/ertc` 的顺序引导
2. 开发者描述具体功能需求时，直接路由到对应模块的知识文件
3. 开发者需要实现具体页面（设备列表、预览、回放、对讲、配网等）时，基于对应模块的 skill 知识文件 + 用户需求生成代码
4. 开发者遇到错误码或异常时，优先查阅 `ezopensdk-errorcode.md`
5. 所有耗时操作（网络请求、设备控制）必须在子线程中调用，UI 更新在主线程
6. 国内客户使用 `EZOpenSDK`，海外客户使用 `EZGlobalSDK`
7. 应用发布时必须关闭 SDK 调试模式（`setDebugLogEnable:NO` + `setDebugStreamEnable:NO`）

### iOS 平台特殊注意事项

1. **播放器必须定义为属性**：`EZPlayer` 定义成局部变量会导致无法播放，必须用 `@property (nonatomic, strong)` 持有
2. **对讲前必须申请麦克风权限**：务必在发起对讲前向 iOS 系统申请 `AVAudioSession` 麦克风权限，否则第一次对讲异常
3. **非国标设备对讲需关闭预览声音**：对讲成功后关闭 `player` 的声音避免回音，对讲结束后恢复
4. **国标设备对讲不能关闭预览声音**：国标设备 talkPlayer 只负责采集手机端声音，设备端声音通过 player 播放
5. **截图是耗时操作**：`capturePicture:` 需在子线程调用
6. **录制文件保存到相册**：SDK 只能录制到沙盒，需开发者自行通过 `PHPhotoLibrary` 转存到系统相册
7. **AP 配网需配置 Signing & Capabilities**：Access WiFi Information + Hotspot Configuration
8. **openssl 版本冲突**：最新版 SDK 内置 openssl 3.0.17，与其他三方库的 openssl 可能冲突，建议使用动态库
