花椒直播推流SDK接入文档
适用 SDK：@hj-live/hjpusher 1.0.13 更新日期：2026-06-09
一、文档目的
本文档用于指导 HarmonyOS 应用接入 花椒直播推流SDK，并说明涉及视频信息、音频信息和人脸信息的 API 调用时机、关闭方式和合规注意事项。
二、工程信息和权限
| 项目 | 内容 |
|---|---|
| SDK名称 | 花椒直播推流SDK |
| SDK包名 | @hj-live/hjpusher |
| SDK版本 | 1.0.13 |
| SDK类型 | 按 T/GIIC0005—2025 附录A划分：实时音视频类 |
| SDK形态 | HarmonyOS HAR 包 |
| 开发者 | 北京密境和风科技有限公司 |
| 声明权限 | ohos.permission.CAMERA、ohos.permission.MICROPHONE、ohos.permission.INTERNET |
| 联系方式 | kefu@huajiao.tv，400-6768-666 |
| HAR 文件 | hjpusher.har |
| HAR SHA-256 | 733db472ea7201c961b54d7f343e2f03154f0bfbed1b6ccc7223e6562f156cfe |
三、标准接入流程
1. 在应用隐私政策及第三方 SDK 清单中披露 SDK 名称、提供方、版本、包名、主要功能和个人信息处理规则。
2. 用户同意应用隐私政策后，可调用 HJPusher.contextInit(true, logDir, logLevel, logMode, maxSize, maxFiles) 初始化日志与上下文。
3. 用户主动点击预览或直播后，申请 CAMERA/MICROPHONE 权限；权限被拒绝时不调用 openPreview/openPusher。
4. 创建 HJPusher 实例并 createPusher；构造 PreviewInfo 后 openPreview 获取 NativeImage surfaceId；将 surfaceId 绑定到 CameraKit PreviewOutput；再通过 XComponent setWindow 绑定预览画面。
5. 用户点击开始直播后，构造 PusherConfig 和 MediaStateInfo 并调用 openPusher；停止时按 closePusher、释放 CameraKit、closePreview、destroyPusher 顺序释放。
四、核心 API 与合规注意事项
| API | 调用阶段 | 处理信息/功能 | 合规要点 |
|---|---|---|---|
| HJPusher.contextInit(valid, logDir, logLevel, logMode, maxSize, maxFiles) | 进程初始化 | 配置日志与上下文，不触发摄像头/麦克风采集。 | 隐私政策同意后调用，避免在日志中写入敏感信息。 |
| openPreview / closePreview | 预览前/预览结束 | 创建 NativeImage surface 并接收摄像头视频信息。 | CAMERA 授权后调用；停止时 closePreview 并释放相机。 |
| openPusher / closePusher | 开始/停止直播 | 按接入方配置 URL 传输音视频信息。 | 完成权限授权和推流告知后调用。 |
| openRecorder / closeRecorder | 扩展功能 | 将音视频内容录制到接入方指定路径。 | 用户主动开启后调用；接入方负责保存期限和清理。 |
| openSpeechRecognizer / closeSpeechRecognizer | 扩展功能 | 回调音频数据 ArrayBuffer。 | 属于音频信息可选处理，应单独告知用途并提供关闭入口。 |
| HJFaceDetectMgr.openFaceDetect / closeFaceDetect | 扩展功能 | 端侧人脸检测，产生人脸框、角度、置信度、关键点信息。 | 人脸信息为可选个人信息，建议单独同意；关闭时 closeFaceDetect 并 nativeSourceClose。 |
| openFaceu/closeFaceu、setFaceProtected(false)、nodeEnable(false) | 扩展功能 | FaceU、人脸保护和图节点效果控制。 | 依赖人脸检测时需显著提示；关闭后不再使用人脸结果。 |
五、可选扩展功能接入示例
| 能力 | 开启示例 | 关闭示例 |
|---|---|---|
| 本地录制 | hjPusher.openRecorder({ recordUrl }) | hjPusher.closeRecorder() |
| PNG 序列/礼物叠加 | hjPusher.openPngSeq(url); hjPusher.setGiftPusher(true) | hjPusher.setGiftPusher(false) |
| 双屏推流 | hjPusher.setDoubleScreen(true) | hjPusher.setDoubleScreen(false) |
| 静音 | hjPusher.setMute(false) | hjPusher.setMute(true) |
| 语音数据获取 | hjPusher.openSpeechRecognizer(cb) | hjPusher.closeSpeechRecognizer() |
| 人脸检测 | faceDetectMgr.openFaceDetect() | faceDetectMgr.closeFaceDetect(); hjPusher.nativeSourceClose() |
| FaceU/图节点 | hjPusher.openFaceu(url) 或 nodeEnable(..., true, ...) | hjPusher.closeFaceu() 或 nodeEnable(..., false, ...) |
| 人脸保护 | hjPusher.setFaceProtected(true) | hjPusher.setFaceProtected(false) |
| RTE 图节点控制 | nodeCreate/nodeConnect/nodeSetParam/nodeEnable | nodeEnable(false)/nodeDisconnect/nodeDelete |
六、发布和排查要点
发布前应核对 module.json5 中 CAMERA、MICROPHONE、INTERNET 权限，应用隐私政策和 SDK 下载页中的版本、包名、HAR SHA-256 与实际送检包一致。排查预览黑屏时优先检查 CAMERA 授权、openPreview 返回的 surfaceId、CameraKit 绑定和 setWindow 节点信息。