netease-uuyc/uuremote-integration-guide

uuremote-integration-guide

概述

1. 安装检测

1.1 iOS 前置配置

<key>LSApplicationQueriesSchemes</key>
<array>
    <string>uuremote</string>
</array>

1.2 iOS 检测方法

func isUURemoteInstalled() -> Bool {
    guard let url = URL(string: "uuremote://external") else { return false }
    return UIApplication.shared.canOpenURL(url)
}

1.3 iOS 未安装处理

1.4 Android 前置配置

<queries>
    <intent>
        <action android:name="android.intent.action.VIEW" />
        <data android:scheme="uuremote" />
    </intent>
</queries>

1.5 Android 检测方法

fun isUURemoteInstalled(context: Context): Boolean {
    val intent = Intent(
        Intent.ACTION_VIEW,
        Uri.parse("uuremote://external")
    )
    return intent.resolveActivity(context.packageManager) != null
}

1.6 Android 未安装处理

2. 设备绑定

2.1 触发方式

uuremote://external/device/authorize?callback=<回调URL>&nonce=<随机ID>

2.2 请求参数

2.3 iOS 调用示例

let callback = "myapp://bindresult"
let nonce = UUID().uuidString
let encodedCallback = callback.addingPercentEncoding(withAllowedCharacters: .urlQueryAllowed) ?? callback
let urlString = "uuremote://external/device/authorize?callback=\(encodedCallback)&nonce=\(nonce)"

if let url = URL(string: urlString) {
    UIApplication.shared.open(url)
}

2.4 UU 远程内部流程

拉起 UU 远程
    |
    +-- 未登录或首页未就绪 -> 排队等待，最长 180 秒
    |       +-- 期间被新的绑定请求取代，或同批只保留最新一条 -> 回调 error=superseded
    |       +-- 排队期间用户退出登录 -> 回调 error=logout
    |       +-- 窗口内仍未完成登录 -> 回调 error=timeout
    |
    +-- 登录态与首页条件满足 -> 进入绑定流程
    |
    +-- 首页设备列表加载中 -> 等待加载完成，最长 15 秒 -> 超时回调 error=timeout
    |
    +-- 过滤设备平台，仅保留 Windows/macOS 设备
    |
    +-- 过滤后设备列表为空 -> 展示“当前无可关联设备”提示 -> 用户点击确认后回调 error=no_device
    |
    +-- 过滤后设备列表非空 -> 弹出设备选择页面
        +-- 用户选择设备并确认 -> 回调 anonymous_device_id
        +-- 用户取消（关闭按钮 / 下拉关闭 / 页面被关闭）-> 回调 error=user_cancel
    |
    +-- 页面栈缺失或无可用展示宿主 -> 回调 error=internal_error

2.5 回调参数

绑定成功

<callback>?anonymous_device_id=<加密设备ID>&nonce=<原始nonce>

绑定失败

<callback>?error=<错误码>&nonce=<原始nonce>

2.6 iOS 回调接收示例

func application(
    _ app: UIApplication,
    open url: URL,
    options: [UIApplication.OpenURLOptionsKey: Any] = [:]
) -> Bool {
    guard let components = URLComponents(url: url, resolvingAgainstBaseURL: false) else {
        return false
    }
    let params = Dictionary(uniqueKeysWithValues:
        (components.queryItems ?? []).compactMap { item in
            item.value.map { (item.name, $0) }
        }
    )

    if url.host == "bindresult" {
        if let deviceId = params["anonymous_device_id"] {
            UserDefaults.standard.set(deviceId, forKey: "bound_device_id")
        } else if let error = params["error"] {
            print("绑定失败: \(error)")
        }
        return true
    }
    return false
}

2.7 Android 调用与回调接收

val callback = "myapp://bindresult"
val nonce = UUID.randomUUID().toString()
val url = "uuremote://external/device/authorize" +
        "?callback=${URLEncoder.encode(callback, "UTF-8")}" +
        "&nonce=$nonce"
startActivity(Intent(Intent.ACTION_VIEW, Uri.parse(url)))

3. 发起远控

3.1 触发方式

uuremote://external/device/control?anonymous_device_id=<加密设备ID>&window_type=<窗口模式>[&callback=<回调URL>]

3.2 请求参数

3.3 窗口模式说明

全屏模式（window_type=0）

小窗模式（window_type=1）

3.4 调用示例

iOS

let deviceId = UserDefaults.standard.string(forKey: "bound_device_id") ?? ""
let callback = "myapp://controlresult"
let windowType = 1

let encodedDeviceId = deviceId.addingPercentEncoding(withAllowedCharacters: .urlQueryAllowed) ?? deviceId
let encodedCallback = callback.addingPercentEncoding(withAllowedCharacters: .urlQueryAllowed) ?? callback
let urlString = "uuremote://external/device/control?anonymous_device_id=\(encodedDeviceId)&window_type=\(windowType)&callback=\(encodedCallback)"

if let url = URL(string: urlString) {
    UIApplication.shared.open(url)
}

Android

val deviceId = URLEncoder.encode(savedDeviceId, "UTF-8")
val callback = URLEncoder.encode("myapp://controlresult", "UTF-8")
val url = "uuremote://external/device/control" +
        "?anonymous_device_id=$deviceId&window_type=1&callback=$callback"
startActivity(Intent(Intent.ACTION_VIEW, Uri.parse(url)))

3.5 回调参数

小窗模式连接成功

<callback>?status=success

小窗模式连接失败

<callback>?status=failure&reason=<失败原因>

reason 取值

3.6 回调约定

3.7 iOS 回调接收示例

if url.host == "controlresult" {
    switch params["status"] {
    case "success":
        print("远控连接成功")
    case "failure":
        let reason = params["reason"] ?? "connect_failed"
        if reason == "device_not_found" {
            UserDefaults.standard.removeObject(forKey: "bound_device_id")
            // 引导用户重新执行设备绑定
        } else {
            print("远控连接失败: \(reason)")
        }
    default:
        break
    }
}

4. 异常和错误处理

4.1 通用异常

4.2 绑定流程异常

4.3 远控连接异常

4.4 超时机制

4.5 注意事项

附录：协议速查

绑定协议

-> uuremote://external/device/authorize?callback={url}&nonce={uuid}
<- {callback}?anonymous_device_id={encrypted_id}&nonce={uuid}
<- {callback}?error={error_code}&nonce={uuid}

远控协议

-> uuremote://external/device/control?anonymous_device_id={encrypted_id}&window_type={0|1}[&callback={url}]

window_type=0（全屏）：
<- 不回调

window_type=1（小窗，传入 callback 时）：
<- {callback}?status=success
<- {callback}?status=failure&reason={reason}

window_type=1（小窗，未传入 callback 时）：
<- 不回调