抖音SDK -直播接入说明
一、前言
- 目前抖音SDK 提供三大产品能力,分别是直播能力,短视频能力,开播能力,此接入说明针对直播能力,接入说明的技术内容仅供开发者参考,若确定要进行接入请通过工单-技术咨询联系官方人员获取正式版技术文档方可顺利接入。
- 特别注意:SDK包您将通过技术支持获得,暂不会提供公开的SDK。
- 目前对外提供的直播接入能力仅 Android 端,接入方可获取抖音直播内容,实现流量分成进行多样化流量变现
二、抖音 SDK -直播接口说明
- 对外文档仅披露部分内容,具体详细内容可见正式版技术文档
1. 服务端侧接入方法
- 开发者通过相关接口所获取的所有数据及信息,均仅能为抖音SDK服务合作目的使用。开发者不得超出范围使用,否则对因此而引起的纠纷或争议,均由开发者自行解决并承担责任,给抖音或其关联方造成损失的,还应当全额赔偿。
- 抖音SDK对外接口符合抖音开放平台的标准,并增加一些自定义的请求头和请求方式(如JSON)。其它如鉴权ClientAccessToken,错误码,返回值格式等均使用抖音开放平台的标准实施。
1.1 开放接口功能说明
接口 | 使用场景示例 |
---|---|
房间信息 | 用于直播卡片自渲染等 |
房间列表 | 用于在某些列表中插入某一直播数据/卡片等(图文&直播混排、视频&直播混排) |
房间状态变更 | 站外PUSH,用于主播开播通知、直播预约等 |
1.2 通用信息介绍
- 通用请求头(接 口使用)
字段名 | 是否必传 | 说明 | 示例 |
---|---|---|---|
Content-Type | 否 | 正常情况下接口支持json类型和普通的form-urlencoded传输方式; 如果想使用json来传递,则需要指定content-type为application/json 注意默认的form-urlencoded不支持复杂类型,所以推荐使用json传输 | application/json |
Webcast-App-ID | 是 | 在直播申请的app-id,int32类型 | 203317 |
Access-Token | 是 | 服务的 Access-token,生成可以参考生成 client_token,: 使用抖音开放平台“生成client_token”小节返回的access_token即可。 | |
User-Access-Token | 否 | 如果用户已经授权,并且能拿到用户的Access-Token,则需要传递此头; 如果无法拿到用户的Token还需要用户身份,可以在业务请求参数中添加user_identity参数,这在每一个对应的接口中都会有说明; 注意user_identity可以代替User-Access-Token,但反之则不行 |
- 通用回调头(回调使用)
字段名 | 类型 | 说明 | 示例 |
---|---|---|---|
event_id | string | 请求的唯一id,可以用于保证幂等 | |
event_type | string | 回调事件类型 | |
create_time | int64 | 这条回调的创建时间 | |
token | string | 开发者在抖音直播保存的字符串,用于校验回调来源的合法性 | |
app_id | int32 | 回调的开发者appid |
- 错误码
通用的错误码同抖音开放平台,但并不是都使用到,如下列出所有抖音直播用到的错误码
错误码 | 说明 |
---|---|
10008 | Access-Token或者User-Access-Token不合法或者过期 |
10014 | Access-Token或者User-Access-Token非本应用(clientKey)生成的 |
10004 | 没有接口调用权限 |
2100004 | 系统繁忙,此时请开发者稍候再试 |
2100005 | 参数错误,一般补充信息中会显示哪一个参数错误 |
2180001 | 房间不存在,一般是open_room_id给得不对,或者房间已经关播很久 |
2. Android 侧接入方法
2.1 接入 SDK
- 特别注意:SDK包您将通过技术支持获得,暂不提供公开的SDK
- 直播要求最低andorid版本5.0 (minsdkversion 21),请注意检查是否符合要求
2.2 自测验证
- 接入直播SDK后,强力建议参照下面case验证核心功能是否正常:
|
---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
3. 直播基础功能 Android 侧接入方法
- 直播各项能力都将通过IOuterLiveRoomService接口进行暴露,通过
LivePluginHelper.getLiveRoomService()
可以获取到该接口的实现,具体内容可见正式版技术文档。
三、附录
- 对外文档仅披露部分内容,具体详细内容可见正式版技术文档
附录一:服务端开放接口列表
- 根据实际情况来进行调用
1. 获取房间信息接口列表
- 根据open_room_id批量获取房间的基础信息
- 基本信息
请求域名 | https://webcast-open.douyin.com |
---|---|
请求URI | /openapi/get_room_info/ |
方法 | POST |
2. 获取推荐房间列表
- 获取推荐房间列表,用于在开发者的某些列表中插入直播数据/卡片
- 基本信息
请求域名 | https://webcast-open.douyin.com |
---|---|
请求URI | /openapi/feed/ |
方法 | POST |
3. 回调接口列表
- 房间状态变更事件当特定的主播进行开播、关播时,开发者将收到此事件的通知回调
- 基本信息
事件名 | webcast.room.status_change |
---|---|
主播范围 | 通过主播主动授权、向直播运营申请添加等方式进入白名单的主播列表 |
附录二: Android 侧对外接入常见问题
1. 编译类问题
问题 | 解决方式 |
---|---|
报错信息和直播SDK包含重复资源定义有关 Duplicate resources | 设置android.disableResourceValidation=true |
找不到抖音 授权SDK的依赖/找不到字节侧一些库依赖 | 根据文档检查maven引入是否正确 |
release编译不过,错误信息和proguard有关 | 尝试android.enableR8=false来关闭R8检查是否和R8有关。 以及尝试开启-dontoptimize 来检查是否和优化器有关。 按照“其他编译问题”处理,并将上述尝试的结果一起提交给字节侧。 |
其他编译问题 | 请联系技术支持同学,并附上如下信息 1.使用命令行编译,并在最后添加 --stacktrace 例如:./gradlew :app:assemble --stacktrace 得到的编译错误日志。 2../gradlew :app:dependencies 得到的依赖树 |
和穿山甲SDK有类冲突,关键字“downloader” | 需要移除downloader类,group: 'com.bytedance.ies.social.base', module: 'downloader' |
2. 功能性问题
- 遇到以下问题时,请附上问题APK及使用的repo,crash请携带完整crash信息,至工单处发起oncall(一个链接)。如果是release包的话,请给出crash信息中,和直播有关的堆栈的mapping信息。
问题 | 解决方式 |
---|---|
初始化直接crash,一个native的crash | 查看安全SDK的签名字符串是否正确配置,如果确认正确配置,至工单处发起oncall |
初始化直接crash,其他crash | 根据crash信息自查,如果自查没有信息的话,可把相关crash信息带上,至工单处发起oncall |
初始化没crash,但是初始化成功没有走 | 至工单处发起oncall |
直播广场入口,无法进入直播间,无错误提示。 | 自行实现IHostAction并作为初始化参数(Builder中同样支持此参数),并在startLive方法中调用DefaultLivePlayerActivity.start(context, roomId, bundle)开启直播,并try catch此调用。 如果调用未发生,至工单处发起oncall。 如果调用发生且发生crash,请根据crash信息自行调整。 如果调用发生且未发生crash,请检查授权实现中isLogin是否返回true。 |
直播广场入口,无法进入直播间,有错误提示,进入直播间,然后显示错误提示切换到下个直播间,几次切换后退出。 | 打印依赖树,检查rangersapplog版本是否是530. 直播尚未兼容高于此版本的rangersapplog |
直播广场入口,无法进入直播间,有错误提示,其他。 | 联络技术支持查看,并将 1.错误信息截图 2.初始化直播代码(Builder的设置/LiveContext的实现) 至工单处发起oncall |
直播广场入口,可以进入直播间,进入后直接crash,feasco相关 | 检查支持的so库版本,直播默认支持armeabi v7a及之上,不支持v5 only。如果有特殊需求请联络相关技术支持。 |
直播广场入口,可以进入直播间,进入后直接crash,发现Lottie有关的crash问题,堆栈来源于一个Lottie NPE。 | 检查Lottie版本,直播只支持2.6.1的Lottie版本 |
直播广场入口,可以进入直播间,进入后不展示流画面,一直loading | 联系技术支持查看,播放器存在鉴权问题,查看播放器id和证书是否正确放置。可以过滤ttmn看是否出现auth failed错误,其他情况请保存日志后至工单处发起oncall。 |
直播广场入口,可以进入直播间,进入后展示流画面,但是一段事件后卡住 | 至工单处发起oncall,播放器存在问题 |
直播广场入口,可以进入直播间,进入后展示流画面,但是尺寸/比例异常 | 至工单处发起oncall,附上主播名称 |
流正常,无法上下滑动切换直播间 | 进房参数错误,至工单处发起oncall。 |
流正常,无更多直播入口 | 直播初始化错误,至工单处发起oncall。 |
PK直播间无PK血条 | 至工单处发起oncall,播放器存在鉴权问题,查看播放器id和证书是否正确放置。可以过滤ttmn看是否出现auth failed错误,其他情况请保存日志。 |
可授权,但是无法互动,弹出错误信息 | 如果弹出的错误信息是未授权,则按照“无法授权”处理。 其他错误至工单处发起oncall。 |
可授权,但是无法互动,也不弹出错误信息 | 至工单处发起oncall。 |
聊天区,自己发出聊天信息会出现两条 | 应用是否在直播间外切换了授权用户?如果有,需要实现IHostUser接口以告知直播SDK发生了用户切换。 内部接入方自行在IBaseHostService中替换IHostUser实现,外部接入方,请关注Live.init的第四个参数,并提供一个自定义的IBaseHostService的实现,将其中IHostUser的实现替换。 如果已经做了上述操作仍存在问题,请检查onTokenInvalid被回调,授权完成后,回调了callback的onSuccess并传入了正确的token。 若问题仍然存在,则按照“无法授权”处理。 |
关注后下滑再返回当前直播间,关注状态被重置 | 账号被风控,至工单处发起oncall。附上当前账号token |