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

# EZOpenSDK Android Skill

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

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

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

### 接入必读
- 仅支持真机调试，不支持模拟器
- 最低系统版本 Android 5.0，JDK 17.0 以上
- 支持架构：armeabi-v7a、arm64-v8a
- 已支持 Android 15 系统 16K PageSize（v5.27 起）

## 功能模块索引

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

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

## 使用指引

1. 三方开发者首次接入时，按 `setup → device → player/talk/wifi/ertc` 的顺序引导
2. 开发者描述具体功能需求时，直接路由到对应模块的知识文件
3. 开发者需要实现具体页面（设备列表、预览、回放、对讲、配网等）时，先询问用户：
   - **选项 A**：参考 `ezopensdk-best-practice.md` 中的 UI 规范和业务逻辑来生成（推荐，可快速获得符合规范的实现）
   - **选项 B**：按用户需求自由发挥，不受 best-practice 约束
   - 用户选择 A 时，读取 `ezopensdk-best-practice.md` 对应模块内容作为生成依据；选择 B 时，仅基于用户描述的需求生成代码
4. 开发者遇到错误码或异常时，优先查阅 `ezopensdk-errorcode.md`
4. 所有耗时操作（网络请求、设备控制）必须在子线程中调用
5. 国内客户使用 `EZOpenSDK`，海外客户使用 `EZGlobalSDK`
6. 应用发布时必须关闭 SDK 调试模式（`showSDKLog(false)` + `setDebugStreamEnable(false)`）

### 异常处理规则（重要）

EZOpenSDK 中几乎所有通过 `EZOpenSDK.getInstance()` 调用的方法都会抛出 `BaseException`（checked exception），生成代码时必须遵守：

```java
// ✅ 正确：try-catch 包裹
try {
    EZOpenSDK.getInstance().controlPTZ(deviceSerial, cameraNo, command, action, speed);
} catch (BaseException e) {
    e.printStackTrace();
}

// ❌ 错误：不捕获异常，编译报错
EZOpenSDK.getInstance().controlPTZ(deviceSerial, cameraNo, command, action, speed);
```

- `BaseException` 的 import 路径：`com.videogo.exception.BaseException`
- 在子线程中调用时，外层通常已有 try-catch；在 UI 线程回调（如 OnTouchListener、OnClickListener）中调用时容易遗漏
- EZPlayer 的方法（startRealPlay、stopRealPlay、startPlayback 等）不抛 checked exception，无需 try-catch
