陌陌弹幕游戏API对接文档
文档更新说明
2024-07-31
1.修改connect接口参数，支持弹幕2.0玩法
2023-11-07
2.优化云端接入说明
2023-09-13
1.connect接口新增versionRead参数用于标识主播所用的游戏版本号,String类型。区别于version（int类型）
2.新增云游戏接入说明
2023-06-07
1.新增房间匹配码登录机制（将于2023-06-12陆续启用）
注: 新增的房间匹配码机制游戏方不需要做更改。connect接口中的momoid现在既可以接收momoid也可以接收房间匹配码，待主播全部更新到最新版直播伴侣后，我们会陆续下掉接收momoid仅保留接收房间匹配码。此过程参数momoid不变，因此游戏方不需要做更改。
2.错误码新增（见文末）
3.pull接口data.payloads.type = gift节点返回字段勘误：giftName修改为gift_name，giftCount修改为gift_count
2023-06-01
1.新增验证码机制流程图（2023-06-12启用）<废弃>
2.新增验证码发送接口/game/sendCode（2023-06-12启用）<废弃>
3./game/connect接口新增入参code用于接收验证码（2023-06-12启用）<废弃>
4.新增发送快捷弹幕接口/game/sendBili（2023-06-12启用）
5.增加常见问题答疑（见文末）
2023-05-17
1.接口文档由轻雀迁移至钉钉文档
﻿
接入流程
1.请根据自身情况确定接入的礼物名称(支持的礼物见文档下方)给到陌陌工作人员
2.请求陌陌工作人员提供 【appId】以及 【appSecret】【测试用陌陌号】
3.根据接口文档(见下)开始开发接入
4.接入完毕 ---> 游戏自测(自测用例如下) ---> 陌陌测试 ---> 上线
弹幕游戏自测用例.xmind附件大小：174.8KB
﻿
游戏流程图﻿﻿
﻿
整体流程时序图﻿﻿
﻿
游戏接入注意事项
注: 目前陌陌弹幕游戏支持PC端obs游戏以及云端游戏，两种模式接口文档一致，但云端游戏需注意以下第2-4点。
1.游戏包启动参数支持-debug和-momodbg两个参数，用以区分不同的环境，需要按照以下逻辑实现支持
-debug用来区分游戏的环境，-momodbg用来区分陌陌的环境，两个参数互相独立，没有关联。
-debug代表游戏沙盒测试环境，不加此参数代表游戏正式环境
-momodbg代表陌陌测试环境， 此时请求陌陌测试域名：https://test-biligame.immomo.com，不加此参数代表陌陌正式环境，此时请求陌陌正式域名: https://live-open.immomo.com﻿
举例：
a. 游戏测试环境，陌陌测试环境启动方式：xxx_game.exe -debug -momodbg （此种方式仅用于陌陌内部测试，游戏方不使用这种场景）
b. 游戏正式环境，陌陌正式环境启动方式：xxx_game.exe （正式上线后的使用方式）
c. 游戏测试环境，陌陌正式环境启动方式：xxx_game.exe -debug  （游戏方测试过程中的使用方式）
游戏方自测说明：
●-debug只控制是否访问游戏方测试环境，游戏方自己测试验证即可。
●-momodbg只控制访问陌陌的域名，游戏方自测时，启动输入不同的参数，保证调用的域名正确即可。
●如果要测整体流程，因游戏方无法整体在陌陌测试环境测试，需使用陌陌提供的测试号，链接陌陌正式域名进行整体流程测试。（即上面的第三种情况，xxx_game.exe -debug）
﻿
2.云端启动标识
云端启动游戏时，启动参数会传入-cloud，游戏方可据此判断是否在云端运行
﻿
3. 游戏包需支持云端全屏
在云端运行时，分辨率必须为：1080 x 1920，且将游戏应用设置为无边框全屏模式
﻿
4. 云端支持自动登录
云端运行时游戏包需要支持数据通道接收房间匹配码。
流程为：游戏进程启动后，监听UDP端口9527，云主机会向该端口发送房间匹配码: -c ${roomCode}。例如: -c olaqhf，游戏识别到房间匹配码olaqhf后，等游戏加载成功后自动登录(等同于PC端主播手动输入房间匹配码登录)。登录成功后向对端发送"login successed"(字符串)。在登录成功前，会定时轮询发送房间匹配码，直到收到"login successed"后停止。
﻿
接口文档
﻿
 接口请求方式: HTTP POST
﻿
 完整接口域名:
正式:  https://live-open.immomo.com/growopen/gameinteraction/{URI}
测试:  https://test-biligame.immomo.com/growopen/gameinteraction/{URI}
URI
请求方式
说明
备注
/game/sendCode
POST
下发登录验证码(1分钟有效)到手机陌陌(陌陌小秘书发送)
废弃
/game/connect
POST
登录连接（开始连接）
必接
/game/disconnect
POST
断开连接
必接
/game/pull
POST
拉取物料（轮询，1秒一次）
必接
/game/update
POST
更新游戏玩法（更新后消息重置）
选接
/game/status
POST
状态查询（用于测试调试阶段）
选接
/game/sendBili
POST
发送快捷弹幕
选接(2023-06-12启用)
1.发送连接验证码(https://live-open.immomo.com/growopen/gameinteraction/game/sendCode) 【弃用】
此接口弃用，请使用房间匹配码模式登录连接，原则上游戏方不需要逻辑更改。
2.开始连接 (https://live-open.immomo.com/growopen/gameinteraction/game/connect)
Request Body:
13
{
  "appId":"xxx",//必须
  "momoid": "xxx",//必须 【注意:历史原因2023-06-12之后启用房间匹配码机制后此字段接收房间匹配码而非主播陌陌号，为了兼容旧版此字段名字不变还叫momoid】
  "playId":"1",//必须，陌陌根据玩法id配置需要收集的信息,默认1即可
  "ts": 1661309627003,//必须，毫秒时间戳
  "version": 1,//必须 int型版本号
  "versionRead":"",//必须 用户可读版本号 eg: 1.2.1
  "reqId": "",//必须 默认传空字符串
  "code": "",//必须 房间码
  "isAudience": false,// 【注意：非弹幕2.0派对玩法的游戏无需传此参数】true是观众，false或者不传视为主播
  "sign": ""//必须 签名计算规则见文末
}
Response Body:
17
{
  "ec": 0,
  "em": "OK",
  "millisecond": 1661309627003,
  "data": {
  	"token":"xxxxxxxxx",//token将作为后续其它接口调用的必传参数
    "starId":"ddd134", //主播uid
    "playId":"xxxx",//对局id
    // 当前用户信息
    "user": { 
    	"uid": "xxx",//UID跟MOMOID一对一关系
  		"name": "宝哥",
	    "avatar": "头像.jpg",
    }
  }
}
﻿
注意:
请求参数中的momoid的值，6.12号之前传递主播momoid，6.12号之后将支持传房间匹配码(房间匹配码为5个小写字母组成，如需逻辑调整请游戏方尽快调整输入框可以输入字母，另外建议输入框提示文字修改为提示主播输入房间匹配码)
﻿
3.断开连接(https://live-open.immomo.com/growopen/gameinteraction/game/disconnect)
Request Header:
2
token:"xxxxxxxxxx"
Request Body:
8
{
  "appId": "xxxx",//必须
  "ts": 1661309627003,//必须
  "version": 1,//非必须，默认1即可
  "reqId": "",//非必须，为空即可
  "sign": ""//必须
}
Response Body:
7
{
  "ec": 0,
  "em": "OK",
  "millisecond": 1661309627003,
  "data": {}
}
﻿
4.物料拉取(https://live-open.immomo.com/growopen/gameinteraction/game/pull)
Request Header:
2
token:"xxxxxxxxxx"
Request Body:
8
{
  "appId": "xxxx",//必须
  "ts": 1661309627003,//必须
  "version": 1,//非必须，默认1即可
  "reqId": "",//非必须，为空即可
  "sign": ""//必须
}
Response Body:
50
{
  "ec": 0,
  "em": "OK",
  "millisecond": 1661309627003,
  "data": {
    // 列表按照ts正序排序
	"payloads":[
      {
      	"type": "gift",//送礼动作
        "ts": 1661309627003,//时间戳
        "gift_name": "玫瑰花",//礼物名称 目前支持的礼物见文档末尾
        "gift_count": 1,//礼物数量 （非连送次数）
        "user": {
          "uid":"",
          "name":"",
          "avatar":""
        }
      },
      {
        "type": "bili",//聊聊(弹幕)动作
        "ts": 1661309627003,
        "content": "蓝",//聊聊内容
        "user": {
          "uid":"",
          "name":"",
          "avatar":""
        }
      },
      {
        "type": "share",//分享动作
        "ts": 1661309627003,
        "user": {
        	"uid":"",
          "name":"",
          "avatar":""
        }
      },
      {
        "type": "follow",//关注动作
        "ts": 1661309627003,
        "user": {
        	"uid":"",
          "name":"",
          "avatar":""
        }
      }
    ]
	}
}
﻿
5.更新游戏(https://live-open.immomo.com/growopen/gameinteraction/game/update)
Request Header:
2
token:"xxxxxx"
Request Body:
9
{
  "playId": "2",
  "appId": "",
  "ts": 1661309627003,
  "version": 1,
  "reqId": "",
  "sign": ""
}
Response Body:
7
{
  "ec": 0,
  "em": "OK",
  "millisecond": 1661309627003,
  "data": {}
}
﻿
6.状态查询(https://live-open.immomo.com/growopen/gameinteraction/game/status)
Request Header:
2
token:"xxxxxx"
Request Body:
8
{
  "appId": "",
  "ts": 1661309627003,
  "version": 1,
  "reqId": "",
  "sign": ""
}
Response Body:
17
{
  "ec": 0,
  "em": "OK",
  "millisecond": 1661309627003,
  "data": {
  	"playId": 1,
    "status":"connecting/disconnected"
    // 主播的游戏信息
    "user": {
      "uid":"",
      "name":"",
      "avatar":""
    },
    "payloads":[]
  }
}
﻿
7.发送快捷弹幕(https://live-open.immomo.com/growopen/gameinteraction/game/sendBili)
Request Body:
7
{
  "appId":"xxx",//游戏appId
  "uid": "xxxx",//发送者UID 
  "msg": "蓝",//快捷弹幕内容
  "sign": ""//签名
}
Response Body:
7
{
  "ec": 0,
  "em": "OK",
  "millisecond": 1661309627003,
  "data": true
}
注意：
请求参数中的uid为观看直播的用户加密momoid，回传给sendBili接口后标识确定的某用户.
uid的获取方式为：游戏方提供展示快捷弹幕的H5网页地址给陌陌，观众uid将会附加到H5网页地址作为参数传给游戏方。
﻿
签名计算规则
22
/**
 * JAVA版本举例
 * 生成签名
 * 规则: 将所有参数(sign除外)的key按字母排序取值拼接后前后继续拼接appSecret后的字符串做Md5加密
 * 参数sign不参与签名
 * @param params 需要签名的参数 key value map
 */
public static String sign(Map<String, ?> params, String appSecret) {
    String signString = params
                .entrySet()
                .stream()
			    .filter(entry -> !"sign".equals(entry.getKey()))//sign不参与签名
                .sorted(Entry.comparingByKey())
                .map(e -> String.valueOf(e.getValue()))
                .collect(Collectors.joining());

    signString = appSecret + signString + appSecret;
    String sign = MD5.hash(signString).toLowerCase();

    return sign;
}
﻿
错误码定义
ec
em
说明
0
ok
接口成功
201
unknown app
app未授权
202
token error
token无效或已过期
203
parameter error
参数错误
204
signature verify failed
签名验证失败
205
access denied
无权访问（非名单主播或直播模式不正确）
206
duplicate request
重复请求
207
expired request
请求过期
208
request too fast
请求频繁
209
live mode error
开播模式不对(请在直播伴侣选择弹幕游戏直播类型)
210
app terminated
游戏已经下线
401
end live
主播关播
402
send code error
发送验证码失败
403
code error
验证码错误
500
server internal error
服务内部错误
501
common error
通用错误码
参数说明
参数
类型
说明
appId
String
必需：线下申请的 appId（由陌陌提供）
ts
int64
必需：毫秒时间戳
version
int32
必需：版本号，目前固定值 1
reqId
String
可选：幂等参数：请求的唯一 id
token
String
标记一次链接的token，链接断开即失效
momoid
String
陌陌号
uid
String
游戏内用户id 一个陌陌号对应一个uid
sign
String
必需：签名, 具体见下方签名计算规则
支持的礼物
礼物
名称
价格
备注
﻿﻿
战旗
1陌币
﻿
﻿﻿
惊喜气球
10陌币
﻿
﻿﻿
战斗宝剑
19陌币
﻿
﻿﻿
白银冲锋令
52陌币
﻿
﻿﻿
来撸串
99陌币
﻿
﻿﻿
刷我的卡
199陌币
﻿
﻿﻿
美味甜筒
299陌币
﻿
﻿﻿
战斗号角
520陌币
﻿
﻿﻿
一起哈啤
666陌币
﻿
﻿﻿
黄金冲锋令
999陌币
﻿
﻿﻿
浪漫加农炮
5200陌币
﻿
﻿
常见问题答疑
1.目前仅支持HTTP轮询模式吗？
答：对。目前仅支持http接入方式。WebSocket接入方式暂不支持
2.pull接口轮询每次最大返回几条数据？
答: 目前每次pull最大返回1000条。
3.轮询建议多久触发一次?
答：建议1s一次
4.pull返回物料中有礼物ID吗？
答：没有。目前使用礼物名称进行区分(中文)
5.disconnect接口什么时机调用？
答：游戏结束主播关闭游戏时候请确保调用disconnect，后续将会作为数据统计分析的依据
6.主播加了白名单但是connect接口还是返回209是为什么？
答：请确保主播开播模式选择正确。参考：https://docs.qq.com/doc/DSWNnUEZraE9haFhQ﻿
7.验证码在2023-06-12启用后没有接入验证码登录会怎样？还能正常玩游戏吗？
答：验证码启用后原来的流程暂时还是可用的，但强烈建议游戏尽快接入验证码机制。
8.2023-06-12启用房间匹配码后原陌陌号登录方式是否还可用？
答：房间匹配码启用之后，原方式还会持续可用一段时间，待主播端直播伴侣全部升级后将会下线。
9.作为主播房间匹配码如何获取呢？
答：打开直播伴侣 --- 弹幕游戏 --- 选择游戏点击下一步 --- 复制房间匹配码
10.有没有接口调用时序图？
答: ﻿