抖音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 |
