MAXHUB开放平台 SDK二次开发接入

MAXHUB 开放平台 SDK 二次开发接入全攻略：从零到一构建智能会议协作应用

摘要：本文系统梳理 MAXHUB 开放平台 SDK 的核心架构、接入全流程、关键业务场景实现及避坑指南，旨在帮助开发者高效完成二次开发，快速构建具备会议协作、白板交互、设备管理能力的企业级应用。

一、 背景与核心价值

随着混合办公模式常态化，企业对会议室设备的可编程性、互联互通及业务定制化需求激增。MAXHUB 开放平台基于 MAXHUB OS（基于 Android 定制） 提供标准化 SDK，开放了会议、白板、设备、账号四大核心能力域，支持开发者以 原生应用 或 系统级服务 形式深度集成，实现“硬件即平台、应用即服务”的生态共建。

二次开发核心优势：

• 零门槛接入硬件能力：无需关注底层驱动，直接调用摄像头追踪、麦克风阵列降噪、电容笔/红外触控等专有硬件能力。
• 会议全生命周期托管：从预约、入会、投屏、录制到纪要生成，全流程 API 覆盖。
• 白板生态共建：接入无限画布、实时协同、文档转白板，打造差异化协作体验。
• 统一设备运维视角：远程批量配置、固件升级、状态监控，降低 IT 运维成本。

二、 核心架构与能力矩阵

1. 技术架构分层

整体技术架构自上而下分为六层：

1. 开发者应用层：开发者 App 调用 SDK，实现会议、白板、设备管控等业务功能。
2. MAXHUB SDK 接入层：向下封装为四个 Kit——Meeting Kit（会议能力）、Whiteboard Kit（白板能力）、Device Kit（设备能力）、Account Kit（账号/权限）。
3. 系统服务层：承接上述四个 Kit 的统一调度与业务编排。
4. MAXHUB OS / Android Framework：提供系统级运行环境。
5. 硬件抽象层 HAL：对接摄像头、麦克风、显示屏等底层硬件。

2. 核心能力矩阵

三、 接入前置条件与环境准备

1. 硬件与系统要求

• 设备型号：MAXHUB V5/V6/V7 系列及新款会议平板（需搭载 MAXHUB OS 3.0+）。
• 系统版本：Android 11 (API 30) 或以上，建议适配 Android 13/14 特性（如通知权限、前台服务类型）。
• 开发者模式：设置 -> 关于设备 -> 连续点击版本号开启 -> 开启“USB调试”及“通过网络调试”。

2. 开发者账号与应用创建

1. 登录 MAXHUB 开放平台控制台。
2. 完成企业实名认证。
3. 创建应用：选择 “原生应用” 或 “系统级服务”（需申请特权签名）。
4. 获取 AppKey / AppSecret 及 OAuth2.0 重定向 URI 配置。

3. 依赖接入

// build.gradle (Project)
allprojects {
    repositories {
        maven { url 'https://maven.maxhub.com/repository/maven-public/' } // 官方 Maven 仓库
        google()
        mavenCentral()
    }
}

// build.gradle (Module)
dependencies {
    // 核心基础库 (必选)
    implementation 'com.maxhub.sdk:core:3.5.+'
    
    // 会议能力模块
    implementation 'com.maxhub.sdk:meeting-kit:3.5.+'
    
    // 白板能力模块
    implementation 'com.maxhub.sdk:whiteboard-kit:3.5.+'
    
    // 设备管理模块
    implementation 'com.maxhub.sdk:device-kit:3.5.+'
    
    // 适配 AndroidX 生命周期与协程
    implementation 'androidx.lifecycle:lifecycle-runtime-ktx:2.7.0'
    implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3'
}

4. 权限与混淆配置

AndroidManifest.xml 关键权限声明：

<!-- 网络与发现 -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_MULTICAST_STATE" /> <!-- 投屏发现必需 -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

<!-- 会议/媒体相关 (Android 13+ 需细分权限) -->
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" /> 
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_CAMERA" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MICROPHONE" />

<!-- 系统级特权 (仅系统签名应用可用) -->
<!-- <uses-permission android:name="com.maxhub.permission.MANAGE_DEVICE" /> -->

ProGuard 混淆规则 (proguard-rules.pro)：

# 保留 SDK 核心模型与回调
-keep class com.maxhub.sdk.** { *; }
-keep interface com.maxhub.sdk.** { *; }

# 保留 Gson/Protobuf 序列化字段
-keepclassmembers class * {
    @com.google.gson.annotations.SerializedName <fields>;
}

# 协程与 Flow
-keep class kotlinx.coroutines.** { *; }

四、 核心接入流程：四步走战略

Step 1：SDK 初始化与认证授权

最佳实践：在 Application 子类中全局初始化一次，使用协程处理异步登录流程。

// MyApplication.kt
class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        // 1. 核心初始化 (Context, AppKey, AppSecret, 环境: RELEASE/DEBUG)
        MaxHubSDK.init(this, "YOUR_APP_KEY", "YOUR_APP_SECRET", Env.RELEASE)
        
        // 2. 设置全局日志级别 (发布前建议关闭 DEBUG)
        MaxHubSDK.setLogLevel(LogLevel.INFO)
        
        // 3. 预登录/静默登录 (若有本地 Token 缓存)
        autoLoginIfNeeded()
    }

    private fun autoLoginIfNeeded() {
        val token = PreferenceManager.getString("access_token", "")
        if (token.isNotBlank()) {
            CoroutineScope(Dispatchers.IO).launch {
                try {
                    AuthKit.refreshToken(token) // 刷新 Token 有效性
                    // 登录成功，可获取用户信息、企业信息
                } catch (e: MaxHubException) {
                    // Token 失效，清理本地缓存，引导用户扫码登录
                    clearLocalAuth()
                }
            }
        }
    }
}

扫码登录交互流程：

1. App 调用 AuthKit.getQRCode() 获取二维码 URL/Image。
2. 界面展示二维码，轮询 AuthKit.pollingQRCodeStatus(qrCodeId)。
3. 用户手机端 MAXHUB App 扫码确认授权。
4. SDK 返回 AccessToken、RefreshToken、ExpiresIn -> 本地加密存储。

Step 2：会议能力集成—— 从“入会”到“投屏”

场景 A：一键入会 / 匿名入会

// MeetingViewModel.kt
fun joinMeeting(meetingNumber: String, password: String?, displayName: String) {
    viewModelScope.launch {
        try {
            // 1. 校验会议号格式
            if (!MeetingKit.isValidMeetingNumber(meetingNumber)) throw IllegalArgumentException("会议号格式错误")
            
            // 2. 构建入会参数
            val params = JoinMeetingParams.Builder()
                .setMeetingNumber(meetingNumber)
                .setPassword(password ?: "")
                .setDisplayName(displayName)
                .setAudioOn(true) // 默认开麦
                .setVideoOn(false) // 默认关摄像头
                .setMuteOnEntry(true) // 入会静音 (大型会议推荐)
                .build()

            // 3. 发起入会 (异步回调)
            MeetingKit.joinMeeting(params) { result ->
                when (result) {
                    is Result.Success -> {
                        // 入会指令下发成功，等待 onMeetingJoined 回调
                        Log.i(TAG, "入会指令发送成功: ${result.data}")
                    }
                    is Result.Failure -> handleMeetingError(result.exception)
                }
            }
        } catch (e: Exception) { handleMeetingError(e) }
    }
}

// 实现 MeetingListener 接收状态回调
private val meetingListener = object : MeetingListener {
    override fun onMeetingJoined(meetingInfo: MeetingInfo) {
        // UI 跳转至会议主界面，获取会中控制器
        meetingController = MeetingKit.getMeetingController()
    }
    override fun onMeetingError(error: MeetingError) { /* 网络断开、被踢出、会议结束 */ }
    override fun onUserListChanged(users: List<MeetingUser>) { /* 更新成员列表 */ }
}

场景 B：无线投屏发射端开发 (核心差异化能力)

MAXHUB SDK 封装了 私有投屏协议 (MaxCast)，兼容 Miracast/AirPlay/DLNA，抗弱网性能优于开源方案。

// ProjectionManager.kt
class ProjectionManager(private val context: Context) {
    private val projectionKit = ProjectionKit.getInstance()
    private var currentSession: ProjectionSession? = null

    fun startDiscovery(listener: DeviceDiscoveryListener) {
        // 发现同网段 MAXHUB 设备
        projectionKit.startDiscovery(object : DiscoveryCallback {
            override fun onDeviceFound(device: CastDevice) {
                // device: name, ip, model, capabilityFlags (支持4K/触控反控/音频传输)
                listener.onFound(device)
            }
            override fun onDiscoveryFailed(error: Throwable) { }
        })
    }

    fun connectAndProject(targetDevice: CastDevice, source: ProjectionSource) {
        viewModelScope.launch {
            val connectResult = projectionKit.connect(targetDevice.deviceId).await()
            if (connectResult.isSuccess) {
                currentSession = connectResult.data
                // 选择投屏源: SCREEN (系统屏幕捕获需 MediaProjection 权限), CAMERA, LOCAL_FILE, CUSTOM_SURFACE
                currentSession?.startProjection(source, object : ProjectionCallback {
                    override fun onStats(stats: ProjectionStats) {
                        // 实时监控: bitrate, fps, latency, packetLoss, rtt
                        updateUIStats(stats)
                    }
                    override fun onError(error: ProjectionError) { /* 弱网重连、编码失败 */ }
                })
            }
        }
    }
    
    // 触控反控事件注入 (接收端触摸坐标回传)
    fun injectTouchEvent(event: MotionEvent) {
        currentSession?.injectInputEvent(event)
    }
}

Step 3：白板能力集成—— 文档协同与无限画布

白板 SDK 采用 View 分离架构：WhiteboardView 负责渲染，WhiteboardEngine 负责逻辑/网络同步。

// WhiteboardFragment.kt
class WhiteboardFragment : Fragment() {
    private lateinit var boardView: WhiteboardView
    private var engine: WhiteboardEngine? = null

    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        boardView = view.findViewById(R.id.whiteboard_view)
        
        // 1. 创建引擎 (支持指定存储路径、缓存大小)
        engine = WhiteboardKit.createEngine(context, EngineConfig.Builder()
            .setCacheDir(File(context.cacheDir, "wb_cache"))
            .setMaxCacheSize(500 * 1024 * 1024) // 500MB
            .enableHardwareAcceleration(true)
            .build()
        )

        // 2. 绑定 View 与 Engine
        engine?.bindView(boardView)

        // 3. 创建/加入房间 (实时协同核心)
        joinBoardRoom("room_12345", "user_001")
    }

    private fun joinBoardRoom(roomId: String, userId: String) {
        val roomConfig = RoomConfig.Builder()
            .set            .setRoomId(roomId)
            .setUserId(userId)
            .setUserName("开发者")
            .setPermission(Permission.READ_WRITE) // 或 READ_ONLY
            .build()

        engine?.joinRoom(roomConfig, object : RoomCallback {
            override fun onRoomStateChanged(state: RoomState) {
                when (state) {
                    RoomState.CONNECTED -> Log.i(TAG, "白板房间连接成功，开始同步历史数据")
                    RoomState.SYNC_COMPLETED -> Log.i(TAG, "历史数据同步完成，可正常书写")
                    RoomState.DISCONNECTED -> handleReconnect()
                }
            }

            override fun onError(error: WhiteboardError) {
                // 处理 Token 过期、房间不存在、版本不兼容等错误
            }
        })
    }

    // 动态添加 PPT/PDF 文件转码任务
    fun addCourseware(fileUrl: String, fileName: String) {
        val task = TranscodeTask.Builder()
            .setUrl(fileUrl)
            .setFileName(fileName)
            .setPriority(TranscodePriority.HIGH)
            .setCallback(object : TranscodeCallback {
                override fun onProgress(progress: Int) { /* 更新 UI 进度条 */ }
                override fun onSuccess(result: TranscodeResult) {
                    // result.scenePath 为白板场景路径，调用 engine?.insertScene(result.scenePath)
                    engine?.insertScene(result.scenePath)
                }
                override fun onFailed(error: TranscodeError) { /* 降级处理：仅显示文件名占位图 */ }
            })
            .build()
        WhiteboardKit.getTranscodeManager().addTask(task)
    }

    override fun onDestroyView() {
        super.onDestroyView()
        engine?.unbindView()
        engine?.destroy()
    }
}

四、核心进阶场景与最佳实践

4.1 会议联动：投屏 + 白板 + 会控的“三位一体”架构

在真实会议室场景中，三大 SDK 并非孤立存在，需通过 会议状态机 统一编排：

架构建议：在 Application 层维护一个 MeetingController 单例，持有 ProjectionKit、WhiteboardEngine、MeetingService 引用，通过 EventBus / Flow 分发会议生命周期事件，避免 UI 层直接耦合 SDK 细节。

4.2 触控反控：从“坐标映射”到“语义交互”

MAXHUB 大屏分辨率通常为 4K (3840×2160)，而投屏源（手机/PC）分辨率各异。简单的线性映射会导致点击偏移。

最佳实践：坐标归一化 + 区域语义修正

// TouchMapper.kt - 坐标映射工具类
object TouchMapper {
    // 将源设备触摸点映射到大屏物理坐标
    fun mapToDisplay(
        sourcePoint: PointF,      // 归一化坐标 0.0~1.0
        sourceRect: Rect,         // 投屏源在大屏上的显示区域 (left, top, right, bottom)
        displayWidth: Int,        // 3840
        displayHeight: Int        // 2160
    ): PointF {
        return PointF(
            sourceRect.left + sourcePoint.x * sourceRect.width(),
            sourceRect.top + sourcePoint.y * sourceRect.height()
        )
    }

    // 语义修正：针对工具栏、系统手势区进行“吸附”或“屏蔽”
    fun semanticCorrect(rawPoint: PointF, displayWidth: Int, displayHeight: Int): PointF {
        val systemGestureThreshold = 48f // 底部/侧边系统手势保留区 48px
        val toolbarRect = Rect(0, displayHeight - 120, displayWidth, displayHeight) // 白板工具栏区域
        
        return if (toolbarRect.contains(rawPoint.x.toInt(), rawPoint.y.toInt())) {
            // 点击工具栏区域 -> 触发工具切换逻辑，不传递给白板绘图层
            PointF(-1f, -1f) // 标记为特殊事件
        } else if (rawPoint.y > displayHeight - systemGestureThreshold) {
            // 底部系统手势区 -> 向上偏移，防止触发系统返回/主页
            PointF(rawPoint.x, displayHeight - systemGestureThreshold - 10)
        } else {
            rawPoint
        }
    }
}

4.3 文档转码与大文件加载优化

PPT/PDF 转码是白板加载耗时的主要来源。针对 100MB+ 复杂动画 PPT，采用 “分页懒加载 + 矢量优先 + 降级兜底” 策略：

1. 服务端预转码：上传文件后立即触发异步转码任务，生成 SVG (矢量) + PNG (位图降级) + JSON (动画元数据) 三套资源。
2. 客户端分级加载：
   • 当前页/前后各 1 页：加载 SVG (无损缩放，支持文本选中)。
   • 非当前页：加载 低分辨率 PNG 缩略图 (占位)。
   • 动画步骤：解析 JSON，驱动白板内部 AnimationPlayer 逐帧渲染。
3. 内存压力防御：实现 LruCache<String, WhiteboardPage>，监听 onTrimMemory(TRIM_MEMORY_RUNNING_LOW) 主动释放非可见页 SVG 资源，仅保留 PNG 缩略图。

五、避坑指南：高频问题与解决方案

六、调试、测试与上线检查清单

6.1 专项调试工具链

1. MAXHUB DevTools (PC 端)：官方提供的可视化调试面板。
   • 投屏链路：实时显示 编码/解码帧率、码率、丢包率、端到端延迟柱状图。
   • 白板协同：查看 Operation Log 流水线、向量时钟版本号、冲突合并耗时。
   • 设备信令：抓取 WebSocket/QUIC 信令交互报文，支持断点重发。
2. 网络弱网模拟：使用 tc (Traffic Control) 或 Charles/Clash 模拟 丢包 5%/10%、延迟 100ms/300ms、带宽限制 2Mbps，验证弱网下的 FEC 前向纠错、NACK 重传、自适应降码率 策略生效情况。
3. 自动化兼容性矩阵：
   • 大屏端：MAXHUB V5/V6/V7 系列 (Android 11/12/13/14)、鸿蒙设备。
   • 投屏源：iOS 16/17 (AirPlay/原生 SDK)、Windows 10/11 (原生 SDK/浏览器 WebRTC)、MacOS、Android 10+。
   • 并发压测：单会议 50 人同时在线，3 路投屏轮切，白板 20 人同写，持续 2 小时无内存泄漏、无 ANR。

6.2 上线前核对清单

• [ ] 证书与签名：Release 包使用正式签名证书，SDK License 已绑定包名 + SHA1，测试证书已移除。
• [ ] 混淆配置：minifyEnabled true，shrinkResources true，通过 R8 精简未用资源。
• [ ] 隐私合规：AndroidManifest.xml 声明 CAMERA、RECORD_AUDIO、MEDIA_PROJECTION 权限理由；隐私政策链接指向最新版本；首次启动弹窗授权逻辑符合《个保法》/GDPR。
• [ ] 埋点上报：关键漏斗 (SDK初始化成功率、投屏连接成功率、白板加载首屏时长、转码成功率) 已接入数据平台，设置告警阈值。
• [ ] 热修复预案：集成 Tinker / Sophix，核心 SDK 调用链路预留反射入口，支持不发版下发 EncoderConfig / WhiteboardConfig 热更参数。

七、未来演进：从 SDK 集成到 “空间计算” 就绪

MAXHUB 开放平台正在向 空间计算 (Spatial Computing) 与 AI Native 方向演进，二次开发者应提前布局：

1. 3D/MR 内容渲染接口：SDK 即将开放 SceneKit / ARCore 兼容层，支持将白板内容投射到 3D 空间，或导入 GLTF/USDZ 模型进行空间标注。建议在白板数据模型中预留 z-index 与 spatialTransform 字段。
2. 大模型原子能力开放：
   • 智能纪要：MeetingKit.generateMinutes(audioStream, whiteboardSnapshots) -> 结构化 Markdown + 待办事项。
   • 代码/图表生成：白板内输入自然语言 "画一个用户登录时序图" -> SDK 返回 Mermaid/PlantUML -> 白板原生渲染可编辑图元。
   • 多模态交互：语音指令 "放大右上角那个表格" -> 语义理解 -> 白板 Viewport 动画聚焦。
3. 边缘计算网关：针对政企私有化部署，提供 边缘网关一体机，将信令、转码、录制、AI 推理全部下沉局域网，满足等保三级/密评合规要求。

八、结语

MAXHUB 开放平台 SDK 的二次开发，本质上是 “将会议室硬件能力抽象为可编程的软件原语” 的过程。

• 投屏 SDK 解决了 “流” 的极致传输与反控；
• 白板 SDK 解决了 “知” 的实时协同与结构化沉淀；
• 会控/设备 SDK 解决了 “器” 的统一调度与环境感知。

优秀的集成方案，不在于调用了多少 API，而在于 如何设计状态机驾驭并发复杂性、如何用工程化手段消解网络不确定性、如何在受限硬件上榨干性能极致。

希望本文从架构选型、核心代码实战、避坑指南到未来演进的全景视角，能为你的开发工作提供确定性的参考坐标。代码的尽头是业务价值，愿你构建出的会议协作应用，真正让“沟通”变得高效、智能、自然。

附录：关键资源链接速查

版本声明：本文基于 MAXHUB 开放平台 SDK v3.5.x / v4.0.x 编写，具体接口签名请以当前下载包内 javadoc / ktdoc 为准。