音视频SDK接入的前后端数据格式约定

如果你正在开发一款需要实时音视频功能的APP，那么这篇文章可能会帮你省下不少调试时间。在实际项目中，我见过太多因为前后端数据格式不统一导致的对接问题——要么是字段名称不一致，要么是数据类型对不上，又或者是在某些边界情况下出现了预期外的响应。今天我想把音视频SDK接入过程中前后端数据格式的约定这件事聊清楚，不讲那些太虚的东西，都是实际开发中会用到的内容。

在开始之前，先简单介绍一下声网。作为全球领先的对话式AI与实时音视频云服务商，声网在音视频通信领域深耕多年，服务覆盖全球超60%的泛娱乐APP。这种大厂出品的SDK，在数据格式设计上通常都有比较完善的规范，但具体到业务层面，还是需要前后端开发人员坐在一起，把数据约定这件事敲定清楚。

为什么数据格式约定这么重要

做过音视频项目的同学应该都有体会，音视频SDK的接入和普通接口对接不太一样。普通接口可能就是个HTTP请求加返回，但音视频涉及到实时传输、状态同步、事件回调等等场景，数据流向是多向的、实时的。如果前端和后端对数据的理解不一致，画面可能卡住、声音可能延迟、用户可能突然掉线——这些问题一旦在线上出现，排查起来真的非常头疼。

我之前接手过一个项目，前端兄弟用的是Web端SDK，后端同学写的是移动端的接口，结果双方对房间状态的字段名定义差了個字母，房间解散的回调愣是没人响应，用户退出房间后还显示在线挂了十几分钟。这种问题其实在设计阶段就能避免，关键就在于数据格式约定的完整性。

核心通信场景与数据流概述

在音视频SDK的接入中，通常会遇到几类核心通信场景。第一类是实时通话场景，包括一对一视频、语聊房连麦这种，需要保证端到端的低延迟。第二类是直播场景，区分主播端和观众端，数据流向不太一样。第三类是互动消息场景，比如实时弹幕、礼物特效、点赞飘屏这类业务数据。第四类是状态同步场景，比如用户上下麦、麦克风开关、摄像头切换这种状态变更。

这几类场景对应的数据格式侧重点各有不同，后面会分别展开讲。先说一个总的原则：所有涉及业务逻辑的数据，都建议采用JSON格式进行前后端交互。JSON的可读性好，调试方便，前后端解析成本低，已经是业界事实上的标准了。

用户认证与房间管理的数据约定

用户要进入音视频房间，第一步就是完成认证。这个环节的数据相对简单，但有几个关键字段需要统一。

用户身份凭证是必须的，声网的SDK通常会要求传入token进行鉴权。这个token应该由你的后端服务器向声网的服务器请求，然后下发给前端。前端在初始化SDK的时候需要用到这个token，另外还有用户的唯一标识ID。在约定字段名称的时候，我建议直接用userId和token这两个名字，简单直观，团队里谁看了都明白。

关于房间管理的核心数据，可以参考下面的格式约定：

字段名称	数据类型	说明
roomId	String	房间唯一标识，建议使用UUID或业务方生成的唯一ID
userId	String	用户唯一标识，需要与鉴权时使用的ID保持一致
role	String	用户角色，如"host"主播、"audience"观众、"interactor"连麦者
token	String	声网SDK鉴权令牌，由服务端动态生成
joinTs	Long	用户加入房间的时间戳，毫秒级

这里有个小细节要提醒一下：roomId在业务层面要区分是长期房间还是临时房间。有些场景比如语聊房，房间可能会持续几个小时甚至更久；而有些场景比如1V1视频，用户匹配成功后才创建房间，匹配失败房间就应该立即销毁。后端在生成roomId的时候，可以考虑加入房间类型的标识前缀，方便区分处理。

实时通话状态数据格式

实时通话是音视频SDK最核心的功能，涉及到的数据格式约定也比较多。我把这类数据分成三类来说：通话参数配置、状态回调数据、以及质量监控数据。

通话参数配置是在用户加入房间前就需要确定好的，包括视频的分辨率、帧率、码率，还有音频的采样率、声道数等。这些参数前端可以直接传给SDK，但后端也需要知道当前房间的通话配置是什么，方便做业务统计和异常排查。建议把这些参数打包成一个config对象，里面用subResolution、frameRate、bitRate这样的命名。

状态回调数据是SDK在通话过程中主动推给业务方的，这类数据通常是通过回调函数或事件监听的方式获取。前后端需要约定好这些事件的格式，比如有人加入了房间、有人离开了房间、有人网络状况变差了、有人开启或关闭了麦克风等等。以用户进出房间为例，建议统一使用类似这样的格式：

• eventType：事件类型，用join表示加入，用leave表示离开
• userId：发生事件的用户ID
• ts：事件发生的服务器时间戳
• reason：离开原因，比如主动退出、超时掉线、被踢出等

质量监控数据是很多团队容易忽略的。声网的SDK其实会实时采集很多网络和质量数据，比如端到端延迟、丢包率、卡顿次数等等。这些数据对于排查问题和优化体验非常重要。建议后端提供一个专门的质量上报接口，前端按固定频率把质量数据推上去，字段可以包括sessionId（一次通话会话的唯一ID）、avgLatency（平均延迟）、packetLossRate（丢包率）、videoBitrate（视频码率）这些核心指标。

直播场景的业务数据约定

秀场直播和1V1社交这类场景，和纯通话场景不太一样的地方在于，它们有更丰富的业务交互。比如观众可以给主播送礼物、可以申请上麦、可以发弹幕点赞。这些业务数据的格式约定，需要兼顾实时性和业务扩展性。

礼物数据是最常见的业务数据之一。一条礼物消息通常会包含这些信息：送礼人ID、收礼人ID、礼物类型ID、礼物数量、礼物价值（如果需要展示的话）、以及发送时间。特别要注意的是，礼物消息可能需要支持高并发推送，所以在数据格式上尽量精简，不要传太多冗余字段。收到礼物后的展示效果配置，建议放在前端本地配置表中维护，后端只需要下发礼物的ID和数量就可以了。

弹幕和点赞这类高频数据，可以考虑做批量推送的优化。比如前端每隔100毫秒收集一次点赞数量，然后一次性上报给后端，后端再以固定频率推送给房间里的其他用户。这样可以大大减少网络请求次数，减轻服务器压力。数据格式可以简化为actionType（区分是弹幕还是点赞）、userId、content（弹幕内容，点赞可以为空）、count（批量数量）。

连麦申请的数据相对复杂一些，因为涉及到状态流转。一个完整的连麦流程可能包括：观众发起申请、主播接受或拒绝、观众上麦、观众下麦。这几个状态变更都需要同步给房间里的所有人。建议用统一的state字段来表示当前状态，比如apply（申请中）、accepted（已接受）、rejected（已拒绝）、connected（已连麦）、disconnected（已断开）。每个状态变更都带一条消息，后端负责维护状态的正确性，前端根据状态显示对应的UI。

实时消息的数据格式规范

实时消息是音视频场景的重要补充功能。声网的SDK通常也提供实时消息的能力，或者可以和专门的IM服务配合使用。不管是哪种实现方式，消息数据的格式约定都是类似的。

单条消息的基本结构应该包含：msgId（消息唯一ID，客户端生成或服务端生成都可以，但必须唯一）、senderId（发送者ID）、receiverId（接收者ID，可以是个人也可以是房间ID）、msgType（消息类型，如text文本、image图片、custom自定义）、content（消息内容，文本消息就是文字，自定义消息就是JSON字符串）、sendTs（发送时间戳）。

自定义消息是个很灵活的功能，可以用来实现很多业务场景，比如房间管理员踢人、禁言、调整用户角色等等。自定义消息的content字段是一个JSON对象，里面放业务具体需要的数据。比如踢人消息的content可能是{"targetUserId":"123","reason":"违反社区规范","banDuration":300}这样。前后端需要为每种自定义消息类型定义好Schema，避免出现解析错误。

消息的排序也是一个需要考虑的问题。在音视频场景中，消息的顺序很重要，比如送礼消息如果顺序乱了，礼物排行榜可能就会算错。建议每条消息都带一个自增的seq字段，服务端按顺序下发，前端按seq排序后渲染。如果出现seq跳跃的情况，说明可能有消息丢失，需要做补偿处理。

状态同步的数据约定

音视频房间里的状态同步是个容易被低估的问题。我见过不少项目，用户已经关闭了麦克风，但其他人和后端数据库里显示的却还是开启状态。这种不同步的根源，往往是数据格式约定的不完善。

用户状态应该包含哪些内容？通常会有：audioState（音频状态，on表示开启，off表示关闭，mute表示静音）、videoState（视频状态，on表示开启，off表示关闭）、screenShareState（屏幕共享状态）、connectionState（网络连接状态，connected/disconnected/reconnecting）。这些状态变更的时候，前端需要立即更新本地的状态显示，同时发一条消息通知后端和其他用户。

状态同步消息的格式建议这样做：每条状态变更消息包含userId、changedStates（变更的状态列表）、ts（变更时间戳）。收到消息的端要对比自己本地的状态，只更新变更的部分，而不是全量覆盖。这样可以减少很多不必要的UI刷新。

异常处理与错误码约定

接入音视频SDK的过程中难免会遇到各种错误，比如网络波动导致的断线、权限不足导致的无法开启摄像头、服务端维护导致的无法连接等等。这些错误的处理逻辑需要前后端紧密配合，错误信息的格式约定就很重要了。

声网的SDK通常会定义一套标准的错误码，前端捕获到错误后，需要把错误码和错误描述一起传给后端，方便后端做日志记录和问题排查。错误数据的格式可以包括：code（错误码，数字类型）、message（人类可读的错误描述）、detail（错误的详细信息，可能包含SDK返回的原始错误）、ts（错误发生时间）。

对于用户可见的错误提示，建议前后端维护一份错误码和用户提示的映射表。后端下发错误码给前端，前端根据映射表展示对应的用户友好的提示文案。这样做的好处是，运营人员如果需要修改错误提示，只需要修改前端代码或者配置，不需要后端发版。

结尾

说了这么多，其实数据格式约定这件事说到底就是一句话：前后端在开始写代码之前，先把数据格式白纸黑字写清楚。不管是用文档、用接口管理工具、还是简单的协作文档，重要的是让团队里每个人都知道数据是怎么流转的、字段是什么意思、边界情况怎么处理。

音视频SDK的接入确实比普通接口要复杂一些，但只要把数据格式约定这件事做扎实了，后续的开发和维护都会顺利很多。如果你所在的团队正在做这件事，希望这篇文章能给你带来一些参考。