netease-uuyc / uuremote-integration-guide

# uuremote-integration-guide
把 UU 远程远控能力接入你的 App —— 设备绑定与发起远控的 URL Scheme 协议说明，覆盖全屏与画中画模式，含 iOS / Android 示例代码与完整错误码。
## 概述
本文档描述第三方 App 与 UU 远程客户端之间的跨 App 交互协议。第三方 App 可以运行在 iOS 或 Android：iOS 通过 URL Scheme 拉起 UU 远程，Android 通过 Deeplink / Intent 拉起 UU 远程。
本文中的平台范围需要区分：
- **调用端平台**：第三方 App 支持 iOS 和 Android，调用方式分别见对应平台示例。
- **目标设备平台**：设备绑定和发起远控目前仅支持 Windows 与 macOS 被控设备。Android、iOS、TV 等其他平台设备不会出现在绑定选择列表中，也不属于本协议支持的远控目标。
协议提供两个核心能力：
1. **设备绑定**：第三方 App 拉起 UU 远程，用户从当前账号下的 Windows/macOS 设备中选择一台进行绑定，UU 远程返回加密后的设备标识。
2. **发起远控**：第三方 App 使用已绑定的设备标识发起远控连接，支持全屏和画中画小窗两种模式。
**UU 远程 URL Scheme**：`uuremote`
**最低版本要求**：iOS 与 Android 客户端均从 **4.42.0** 起支持本协议。
---
## 1. 安装检测
### 1.1 iOS 前置配置
iOS 第三方 App 需在 `Info.plist` 中添加 `LSApplicationQueriesSchemes` 白名单，否则 `canOpenURL` 将始终返回 `false`。
 [code] 
### 1.2 iOS 检测方法
 [code] 
### 1.3 iOS 未安装处理
若检测结果为 `false`，应停止发起绑定或远控请求，并引导用户前往 App Store 安装 UU 远程。
### 1.4 Android 前置配置
Android 11（API 30）及以上的第三方 App 需在 `AndroidManifest.xml` 中声明 ` `，否则应用可见性限制可能导致安装检测失败。
 [code] 
### 1.5 Android 检测方法
 [code] 
UU 远程 Android 正式包名为 `com.netease.uuremote`。包名可用于安装引导或应用市场跳转，不建议仅通过包名查询代替 Deeplink 可用性检测。
### 1.6 Android 未安装处理
若 Intent 无法解析，应停止发起绑定或远控请求，并按接入方既有分发渠道引导用户安装 UU 远程。
---
## 2. 设备绑定
### 2.1 触发方式
第三方 App 通过以下 URL Scheme 拉起 UU 远程的设备绑定流程：
 [code] 
### 2.2 请求参数
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `callback` | String | 是 | 第三方 App 的回调 URL（含 scheme 和 host）。UU 远程完成操作后通过此 URL 回跳。参数值需进行 URL 编码。 |
| `nonce` | String | 否 | 用于匹配请求和回调的随机唯一标识符，建议使用 UUID。传入后，UU 远程会在回调中原样返回。 |
### 2.3 iOS 调用示例
 [code] 
### 2.4 UU 远程内部流程
 [code] 
Android、iOS、TV 等非 Windows/macOS 设备不展示在绑定列表中，不能通过本协议生成 `anonymous_device_id`。
### 2.5 回调参数
UU 远程通过打开第三方 App 的 `callback` URL 返回结果。
#### 绑定成功
 [code] 
| 参数 | 说明 |
|------|------|
| `anonymous_device_id` | 加密后的 Windows/macOS 设备标识。第三方 App 应持久化存储此值，后续发起远控时使用。 |
| `nonce` | 请求中传入 `nonce` 时原样返回；未传入时回传空值（字段仍会出现）。 |
#### 绑定失败
 [code] 
| `error` 值 | 说明 |
|-------------|------|
| `no_device` | 当前 UU 账号下没有可关联的 Windows/macOS 设备 |
| `user_cancel` | 用户主动取消，包括点击关闭按钮或下拉关闭 |
| `timeout` | 排队等待登录（180 秒）或设备列表加载（15 秒）超时 |
| `not_logined` | 排队被触发时已不满足登录态或首页条件，无法继续 |
| `superseded` | 该绑定请求被后发的同类请求取代，或同批请求中未被选中 |
| `logout` | 排队期间用户退出登录，绑定请求被清理 |
| `internal_error` | UU 远程内部异常，无法继续处理（页面栈缺失、无可用展示宿主等），不再细分内部原因 |
绑定成功与失败互斥：成功返回 `anonymous_device_id`，失败返回 `error`。`internal_error` 为兜底错误码，UU 远程不向第三方暴露具体内部原因。
### 2.6 iOS 回调接收示例
第三方 App 需注册自己的 URL Scheme，并在 `AppDelegate` 或 `SceneDelegate` 中处理回调：
 [code] 
### 2.7 Android 调用与回调接收
Android 第三方 App 使用 Intent 拉起 UU 远程。这里的 Android 指第三方调用端平台，不表示支持绑定 Android 被控设备。
 [code] 
第三方 App 需注册自己的 scheme，并在 Activity 中读取 `intent.data` 的 `anonymous_device_id`、`nonce` 或 `error` 参数。
---
## 3. 发起远控
### 3.1 触发方式
第三方 App 通过以下 URL Scheme 发起远控连接：
 [code] 
本接口仅支持通过设备绑定流程获得的 Windows/macOS 设备标识。
### 3.2 请求参数
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `anonymous_device_id` | String | 是 | 绑定流程返回的加密设备标识。参数值需进行 URL 编码。 |
| `window_type` | Int | 否 | 窗口模式：`0` = 全屏，`1` = 画中画小窗；默认值为 `0`。 |
| `callback` | String | 否 | 第三方