接口列表 | 开发文档

# 接口列表

功能描述	请求路径	请求方法	用户授权	备注
设置悬浮窗信息	/setFloatFrame	POST	-	仅限主播模式
设置轮播信息	/setSlideFrame	POST	-	仅限主播模式
隐藏悬浮窗信息	/hideFloatFrame	POST	-	仅限主播模式
获取礼物列表	/getGiftList	GET	-	-
获取当前用户信息	/getUserInfo	GET	是	-
发送公聊区消息	/sendRoomChatMsg	POST	-	仅限主播模式
申请连麦频道号	/applyChannel	POST	-	仅限主播模式
获取主播信息	/getSimpleStarInfo	GET	-	-
获取用户最近送礼记录	/getGiftRecord	GET	是	-
获取用户观看时长	/getWatchTimeInfo	GET	是	需申请权限
获取直播间公聊区消息	/getRoomChatMsg	GET	-	需申请权限，且仅限主播模式
获取直播间送礼记录	/getGiftRecordList	GET	-	需申请权限
场次玩家准备	/matchPlayerReady	POST	-	-
场次结果上报	/reportMatchResult	POST	-	-

说明：

关于小程序模式介绍，请点击查看小程序模式
特殊权限请进入开发者中心申请

# 获取用户authToken

部分开放接口信息需要用户登录/授权后才能获取，小程序通过authToken来校验用户登录/授权，因此需要在接口参数中加入authToken。
获取authToken的方式如下：

1、已经登录的用户，容器会自动在小程序前端访问小程序后端的请求header中加上“authToken”参数。
2、需要授权接口，小程序前端通过sdk包访问FxExt.getUserInfo获取当前用户信息，会自动拉起用户授权框。用户授权过后，容器会自动在访问小程序后端的请求header中加上“authToken”参数。
3、小程序后端在收到前端的请求时，可以从header中获取“authToken”参数，用于请求需要登录/授权状态的open接口。

ps:上述请求接口需要通过由sdk包发起的网络请求FxExt.fetch

# 设置悬浮窗信息

接口说明
- 该接口仅限主播模式小程序调用。
请求地址
```
/setFloatFrame
```
请求参数

参数名	参数类型	约束	描述
id	string	必填/最长32位	唯一标识
appId	string	必填	小程序ID
starId	string	必填	主播openID
time	int	必填	当前时间戳
title	string		主标题
subTitle	string		副标题(内容)
countDownText	string		倒计时文字。如果要在文字中包含倒计时，使用占位符%@。比如在%@秒后结束
countDownStartTime	int		倒计时开始时间。时间戳（秒）
countDownEndTime	int		倒计时结束时间。时间戳（秒）

返回参数

{
  "code": 0,
  "msg": "ok",
  "time": 1598430786,
  "data": true
}

# 设置轮播信息

接口说明
- 该接口仅限主播模式小程序调用。
请求地址
```
/setSlideFrame
```
请求参数

参数名	参数类型	约束	描述
id	string	必填/最长30位	唯一标识
appId	string	必填	小程序ID
starId	string	必填	主播openID
time	int	必填	当前时间戳
interval	int		轮播间隔
slides	list		轮播信息

slides参数结构

参数名	参数类型	约束	描述
slideId	string	必填/最长20位	轮播图ID
title	string		主标题
subTitle	string		副标题

返回参数

{
  "code": 0,
  "msg": "ok",
  "time": 1598430786,
  "data": true
}

# 隐藏悬浮窗信息

接口说明
- 该接口仅限主播模式小程序调用。
请求地址
```
/hideFloatFrame
```
请求参数

参数名	参数类型	约束	描述
id	string	必填/最长32位	唯一标识
appId	string	必填	小程序ID
starId	string	必填	主播openID
time	int	必填	当前时间戳

返回参数

{
  "code": 0,
  "msg": "ok",
  "time": 1598430786,
  "data": true
}

# 获取礼物列表

请求地址

/getGiftList

请求参数（GET请求）

参数名	参数类型	约束	描述
starId	string	必填	主播openID

返回参数

字段名	字段类型	描述
classId	long	分类id
className	string	分类名称
sortIndex	int	分类序号
id	long	礼物id
name	string	礼物名称
pic	string	礼物图标
price	long	礼物价格
category	long	礼物种类
sortIndex	int	礼物序号
image	string	礼物图片
type	int	类型
mobileImage	string	手机端礼物图片

返回参数示例

{
  "code": 0,
  "msg": "ok",
  "time": 1598430786,
  "data": {
    "categories": [
      {
        "classId": 43,
        "className": "经典",
        "sortIndex": 7
      },
      {
        "classId": 28,
        "className": "活动",
        "sortIndex": 9
      }
    ],
    "gifts": [
      {
        "id": 1941,
        "name": "爱神之箭",
        "pic": "http://s1.fx.kgimg.com/fxstatic/images/giftres/1941/a3bad29216081c2a5c13fb628bffc9d5.gif",
        "price": 100,
        "category": 28,
        "sortIndex": 0,
        "status": 1,
        "image": "http://s2.fx.kgimg.com/fxstatic/images/giftres/1941/53c2ce6b488dfb59fa3c4e28b6431c0b.png",
        "type": 0,
        "mobileImage": "http://s1.fx.kgimg.com/fxstatic/images/giftres/1941/f3016be3ad76562e120f038abaa631b0.png"
      },
      {
        "id": 1567,
        "name": "踢踏舞",
        "pic": "http://s2.fx.kgimg.com/fxstatic/images/giftres/1567/a5a2667eb3aba20989b4bbf7e0cd9a49.gif",
        "price": 100,
        "category": 43,
        "sortIndex": 0,
        "status": 1,
        "image": "http://s3.fx.kgimg.com/fxstatic/images/giftres/1567/1cfc6aeb3fe3b11efbcde7e5ef65efb9.png",
        "type": 0,
        "mobileImage": "http://s3.fx.kgimg.com/fxstatic/images/giftres/1567/05f213961e1e291335dff6b6dcd84aae.png"
      }
    ]
  }
}

# 获取当前用户信息

请求地址
```
/getUserInfo
```
请求参数

参数名	参数类型	约束	描述
authToken	string	必填	令牌，获取用户authToken方式

返回参数

字段名	字段类型	描述
nickName	string	昵称
userLogo	string	头像
openId	string	用户openId
userId	long	用户繁星ID

返回数据示例

{
  "code": 0,
  "msg": "ok",
  "time": 1598430786,
  "data": {
    "nickName": "用户昵称",
    "userLogo": "/fxusercmdavata/system.gif",
    "openId": "Mtoe19b/GppMF3+G+xe/5Q==",
    "userId": 357888705
  }
}

# 发送公聊区消息

接口说明
- 该接口仅限主播模式小程序调用。
请求地址
```
/sendRoomChatMsg
```
请求参数

参数名	参数类型	约束	描述
id	string	必填/最长32位	唯一标识
content	string	必填	内容
starId	string	必填	主播openID
appId	string	必填	小程序ID
time	int	必填	当前时间戳

返回参数

{
  "code": 0,
  "msg": "ok",
  "time": 1598430786,
  "data": true
}

# 申请连麦频道号

接口说明
- 该接口仅限主播模式小程序调用。
请求地址
```
/applyChannel
```
请求参数

参数名	参数类型	约束	描述
starId	string	必填	主播openID

返回参数

字段名	字段类型	描述
data	long	连麦频道id

返回结构示例

{
  "code": 0,
  "msg": "ok",
  "time": 1598430786,
  "data": 3176269831
}

# 获取主播信息

请求地址
```
/getSimpleStarInfo
```
请求参数

参数名	参数类型	约束	描述
starId	string	必填	主播openID

返回参数

字段名	字段类型	描述
roomId	int	主播房间号。没有则默认返回0
isStar	boolean	是否主播。true=主播，false=非主播
isLive	boolean	开播状态。true=开播，false=下播

返回数据示例

{
  "code": 0,
  "msg": "ok",
  "time": 1598430786,
  "data": {
    "roomId": 3852716,
    "isStar": true,
    "isLive": false
  } 
}

# 获取用户最近送礼记录

请求地址

/getGiftRecord

请求参数

参数名	参数类型	约束	描述
authToken	string	必填	令牌，获取用户authToken方式
beforeTime	long	必填	距离当前时间的最大值，单位为秒，取值范围：0<beforeTime<=300
sendId	long	否	送礼记录id

最多返回距离当前beforeTime时间内的记录（即使传入sendId），如果未传入sendId，则返回在beforeTime时间内，用户最新的一条送礼记录
如果在指定时间范围内，没有记录，则不返回data字段

返回参数

字段名	字段类型	描述
sendId	string	送礼记录Id
sendUserId	string	送礼用户openId
receiveUserId	string	收礼用户openId
giftId	int	礼物id
giftNum	int	礼物数量
sendTime	string	送礼时间，单位为秒

返回结构示例

{
    "code": 0,
    "msg": "success",
    "data": {
        "sendId": "1440771689972998352",
        "sendUserId": "jKnn9NDLX0jiiElgyiZTyQ==",
        "receiveUserId": "zVZ/J/hjnOflS+9wHL0VZQ==",
        "giftId": 2235,
        "giftNum": 4,
        "sendTime": "1606308042"
    }
}

# 获取用户观看时长

请求地址
```
/getWatchTimeInfo
```
请求参数

参数名	参数类型	约束	描述
authToken	string	必填	令牌，获取用户authToken方式，接口仅限指定开发者开放

返回参数

字段名	字段类型	描述
openId	string	用户openId
watchTimeMin	long	用户当天观看时长，单位：分钟

返回数据示例

{
    "code": 0,
    "msg": "success",
    "data": {
        "openId": "cxO9pmQ1T4i873BhVty/2w==",
        "watchTimeMin": 12
    }
}

# 获取直播间公聊区消息

接口说明
- 该接口仅限主播模式小程序调用。
- 小程序需要申请权限才能使用这个接口。
- 只能返回指定主播房间的公聊区消息（需要申请能查询公聊区信息的房间号id）。
- 小程序需要根据聊天记录id（唯一id）自行校验聊天记录幂等逻辑。
请求地址
```
/getRoomChatMsg
```
请求参数

参数名	参数类型	约束	描述
starId	string	必填	主播openId
beginTime	long	非必填	单位：ms。 1.不传时间戳返回默认条数(默认返回最近200条记录) 2.传时间戳返回该时间之后的记录，只会返回该时间戳后最新的200条记录。

返回参数

字段名	字段类型	描述
chatInfoList	object []	聊天信息列表
├─id	string	消息记录id（唯一id）,小程序需处理幂等逻辑
├─senderOpenId	string	发送者openId，开启神秘嘉宾的用户，openId为空字符串
├─senderNickName	string	发送者昵称
├─senderLogo	string	发送者头像
├─content	string	聊天信息
├─time	long	消息时间
timeStamp	long	返回本次数据的最高时间戳水位，下次请求时beginTime可以从该水位开始(ms)

返回数据示例

{
    "code": 0,
    "msg": "success",
    "data": {
        "chatInfoList": [
            {
                "id": "111112332",
                "senderOpenId": "Bw453FdzVSsZtZFvj7irzg==",
                "senderNickName": "WozAIcgn",
                "senderLogo": "https://p3fx.kgimg.com/v2/fxuserlogo/de04ba0b28fefc700662410a1fe655bc.jpg_45x45.jpg",
                "content": "1112",
                "time": 1607934234356
            }
        ],
        "timeStamp": 1607934245067
    }
}

# 获取直播间送礼记录

接口说明
- 只能返回指定主播房间的礼物信息（需要申请能查询送礼信息的主播号id）。
- 只能返回特定礼物的送礼信息（需要申请返回的礼物id/giftId，目前同个appId不同房间号的能访问的礼物信息相同，不会根据房间号不同配置而不同）。
- 目前只返回5分钟内的用户送礼信息。
- 小程序需要根据送礼记录id（唯一id）自行校验送礼记录幂等逻辑。

请求地址

/getGiftRecordList

请求参数

参数名	参数类型	约束	描述
starId	string	必填	主播openId
beginTime	long	非必填	单位：ms。 1.不传时间戳返回默认条数（默认返回5分钟内的送礼记录）。 2.传时间戳返回该时间之后的记录，送礼记录只能传当前五分钟内的时间戳。

返回参数

字段名	字段类型	描述
giftInfoList	object []	送礼信息列表
├─id	string	送礼记录id（唯一id）,小程序需处理幂等逻辑
├─starOpenId	string	主播openId
├─senderOpenId	string	送礼用户openId，开启神秘嘉宾的用户，openId为空字符串
├─senderNickName	string	送礼用户昵称
├─senderLogo	string	送礼用户头像
├─giftId	int	礼物id
├─giftNum	int	礼物数量
├─time	long	送礼时间
timeStamp	long	返回本次数据的最高时间戳水位，下次请求时beginTime可以从该水位开始(ms)

返回数据示例

{
    "code": 0,
    "msg": "success",
    "data": {
        "giftInfoList": [
            {
                "id": "1449771201013966733",
                "starOpenId": "T61mU2vWiAr86dLBk/Pedw==",
                "senderOpenId": "lYJmUlfCPr4BuF4dPA++dQ==",
                "senderNickName": "490000001",
                "senderLogo": "https://s10.fxwork.kugou.com/fxusercmdavata/18.jpg",
                "giftId": 1,
                "giftNum": 1,
                "time": 1607927590171
            }
        ],
        "timeStamp": 1607931436551
    }
}

# 场次玩家准备

接口说明
- 调用接口前，需调用sdk FxExt.onMatchingResult进行场次初始化操作
- 场次初始化后，所有玩家需在平台统一准备超时时间（1分钟）内完成准备，否则场次自动进入超时状态
- 确保接口返回网络状态码为200，业务状态码为0，其他情况代表操作未成功
请求地址

/matchPlayerReady

请求参数

参数名	参数类型	约束	描述
matchId	long	必填	场次id
openId	string	必填	玩家openID

返回数据示例

{
    "code": 0,
    "msg": "success"
}

# 场次结果上报

接口说明
- 场次初始化后，需在平台统一超时时间（30分钟）内上报结果，否则场次自动进入超时状态
- 确保接口返回网络状态码为200，业务状态码为0，其他情况代表操作未成功
请求地址

/reportMatchResult

请求参数

参数名	参数类型	约束	描述
matchId	long	必填	场次id
endTime	long	必填	场次结束时间戳，单位毫秒
winnerId	string	非必填	胜利玩家openID

返回数据示例

{
    "code": 0,
    "msg": "success"
}

← 调用示例 SDK文档 →