# 快手弹幕玩法客户端接入说明

更新时间：2024-11-22 15:03:56

# warning！！！禁止游戏包热更新，走后台更新游戏包

# 使用最新的PC伴侣线上包：https://live.kuaishou.com/live-partner (opens new window)

# 1、启动参数

快手伴侣启动弹幕玩法（以下简称玩法）时会通过启动参数传给玩法传一些信息。（玩法如果不解析处理启动参数会导致不支持自动填充roomCode码，不能支持进程间通信等，影响主播体验）信息内容如下表：

参数名	类型	说明	示例（以进程名ks1234567890123456.exe为例）
-c	基础能力	建立连接需要的roomCode码	ks1234567890123456.exe -c be3f952e-fcd2-414d-9a85-a863c23a9745 注意：由于roomCode需要开播后才能获得，所以只有在开播后启动玩法伴侣才会有-c命令行参数
-pos	开放能力	建议窗口展示区。格式如 : x,y,width,height。注意：玩法首次启动时，使用建议窗口区域；非首次启动时，忽略建议窗口区域，使用上次关闭时的窗口区域。设置窗口位置方法如下： SetWindowPos(hWnd, HWND_TOPMOST, x, y, width, height, SWP_SHOWWINDOW);	ks1234567890123456.exe -pos 0,0,1080,1920
-ipc	开放能力	进程IPC名字，支持进程通信的开发者，使用该值作为name参数	ks1234567890123456.exe -ipc 23320ae5-ee32-4fab-8c6e-3a7263c535f4 注意：须ks_manifest.json中的ipcSetCode或ipcQuit为true，伴侣会在启动玩法时增加-ipc命令行参数。清单文件说明

注：以上所有参数都可以组合使用。

例如：ks1234567890123456.exe -c be3f952e-fcd2-414d-9a85-a863c23a9745 -pos 0,0,1080,1920 -ipc 23320ae5-ee32-4fab-8c6e-3a7263c535f4

# 2、玩法压缩包制作

弹幕玩法接入快手需要符合一定的要求。强烈推荐使用压缩工具 (opens new window)制作玩法压缩包。

# 2.1、快手弹幕玩法清单文件

弹幕玩法包内需要包含清单文件：ks_manifest.json。(UTF8编码)

文件内容如下：

{
    "version": "1.1.8",          // 废弃
    "launcherFileName": "ks1234567890123456.exe",
  "workFileNames": [
        "IceAndFire.exe",
        "IceAndFire\\Binaries\\Win64\\IceAndFire-Win64-Shipping.exe"
    ],
  "killFileNames": [
        "IceAndFire.exe",
        "IceAndFire\\Binaries\\Win64\\IceAndFire-Winr64-Shipping.exe"
    ],
    "ipcSetCode": false,
    "ipcQuit": false,
    "captureParam": [
        {
      "captureCursor": true,
            "type": "game",
            "wndName": "launcher",
            "wndClass": "UnityWndClass",
            "name": "launcher.exe"
        }
    ],
    "material": {
        "ruleVerticalImageName": "ver_image.png",
        "ruleHorizonImageName": "hor_image.png"
    }
}

字段说明：

字段	类型	说明	备注
version（废弃）	基础能力	弹幕玩法版本	升级版本必须调整版本信息，伴侣依据该字段提示主播升级弹幕玩法注意：为兼容伴侣线上版本，原有的版本文件也需要保留，同时保证verson与原版本文件内容一致
launcherFileName	基础能力	弹幕玩法启动进程在压缩包中的路径	启动文件名一律用appID.exe 且在根目录下如 ks1234567890123456.exe 注意：启动文件务必使用这种格式，否则将打不开游戏
workFileNames	基础能力	弹幕玩法工作进程在压缩包中的路径。	可以不配置，不配置代表和launcherFileName相同启动弹幕玩法后，伴侣会监听列表中的所有进程是否正在运行，如果所有的进程都不存在就会提示异常。
killFileNames	基础能力	结束弹幕玩法时需要清理的进程在压缩包中的路径	可以不配置，不配置代表和workFileNames相同
captureParam	基础能力	画面捕获参数列表 captureCursor：是否捕获鼠标（默认值true） type: 捕获类型（ game:玩法捕获 window:窗口捕获 camera:玩法创建虚拟摄像头，伴侣直接捕获虚拟摄像头并对画面增加美颜效果） wndName：弹幕玩法的窗口名 wndClass：弹幕玩法的窗口类名 name:弹幕玩法进程文件名称，不包含路径（eg：launcher.exe）注意：使用unity、UE开发的游戏支持game和window捕获，使用cocos开发的游戏只支持window捕获当type为camera时需要额外配置如下参数： deviceId：设备id eg: AR大战虚拟摄像头:ARGameVC 其内容为: 设备名称：对应设备属性 FriendlyName 设备路径：对应设备属性 DevicePath resolution：分辨率（默认值1080x1920） eg: resolution":"1080x1920"	填写该字段，通过伴侣启动弹幕玩法后，伴侣会自动捕获弹幕玩法窗口。窗口名和窗口类名获取方式：参数可使用spy++获取(Visual Studio自带工具)，获取方式见视频： ` 则对应参数分别为： wndName：launcher wndClass：UnityWndClass
ipcSetCode	开放能力	支持ipc中的SetCode方法，默认不支持IPC	弹幕玩法启动后接收匹配码。支持该能力伴侣挂件会展示为“开播自动连接” 注意：ipcSetCode或ipcQuit为true，伴侣会在启动玩法时增加-ipc命令行参数，同时在游戏过程中会检测ipc的状态。触发场景:开播前启动玩法，开播后伴侣会通过SC_SET_CODE将最新的匹配码告知玩法
ipcQuit	开放能力	支持ipc中的Quit方法，默认不支持IPC	PC直播伴侣通知弹幕玩法退出。注意：ipcSetCode或ipcQuit为true，伴侣会在启动玩法时增加-ipc命令行参数，同时在游戏过程中会检测ipc的状态。触发场景:主播点击"重启"，对于支持ipc退出的玩法(ks_manifest.json中对用的配置项是ipcQuit)，伴侣会下发SC_QUIT
material	选填	启动弹幕玩法后默认添加到直播源的素材。（暂时只支持图片素材 png 和 jpg）素材信息： ruleVerticalImageName：竖版【规则素材】的文件路径 ruleHorizonImageName：横版【规则素材】的文件路径素材规格: 竖版图片尺寸要求：宽度固定240px，高度最大值424px 横版图片尺寸要求：宽度最大值748px，高度固定124px。展示位置：竖版【规则素材】图片，会展示在右下角，距右侧120像素，距底部172像素横版【规则素材】图片，会展示在画面上方，距顶部500像素，水平方向居中会展示到弹幕玩法源的上方，摄像头源的下方。【规则素材】支持数量：都没有一个竖版一个横版一个竖版和一个横版	以ruleVerticalImageName文件名为例：根目录下可以为： rule_ver_image.png bin目录下则为：bin/rule_ver_image.png

# 2.2、玩法压缩包制作工具

强烈推荐使用本压缩工具制作玩法压缩包。

工具界面如下图所示：

# 2.2.1、工具使用步骤

在AppId右侧的文本框输入弹幕玩法的appid

点击选择路径按钮，选择需要压缩的路径；如果为有效路径，会在下方展示ks_manifest.json文件的内容；否则请按照弹框提示进行检查

击开始压缩按钮，如果目录下的文件符合ks_manifest.json中的要求，开始压缩按钮文案变为压缩中，进度条开始显示压缩进度，压缩完成后压缩文件会保存在选择的目录的上一级目录；如果目录下的文件不符合ks_manifest.json中的要求，请按照弹框提示中的内容进行修改

压缩过程中，开始压缩按钮会变成不可操作状态，直到整个目录压缩完成，按钮重新变成可操作状态，按钮的文案变成压缩完成

压缩完成以后，点击选择路径，可以重新选择目录进行压缩；点击压缩完成，该按钮重新变成开始压缩，可以继续上述操作进行压缩

# 2.2.2、压缩工具提示文案说明 (opens new window)

# 3、IPC （进程通信）

为优化用户整体体验，快手伴侣和玩法间需要通过IPC来做一些协同。IPC部分整体属于开放能力。

为此，快手伴侣会提供进程间通信的SDK (opens new window)。

IPCDLLAPI int InitIpc(const char* name, size_t len, IPC_CS_TYPE type);

注意：创建IPC对象的name参数可以从启动参数(参数名 -ipc)获取到，IPC_CS_TYPE使用CLIENT。

c#接入示例：

cocos+electron接入示例：

ipc库二进制下载链接：https://d4.a.kwimgs.com/kos/nlav12667/kuaishou_ipc/ipc_8fd4d4d.rar (opens new window)

# 3.1、API接入说明

# 3.1.1、c++接口接入

对应头文件：ipc_i.h

namespace kuaishou {
namespace ipc {
enum IPC_CS_TYPE { CLIENT, SERVER, UNKNOWN };

/*
 * data:buffer数据
 * len: buffer数据长度
 */
typedef void(DataReceivedCallback)(const char* data, size_t len, void* user_data);
typedef void(ConnectedCallback)(void* user_data);
typedef void(DisconnectCallback)(void* user_data);
typedef void(LogCallback)(const char* data, size_t len, void* user_data);

 /*
IPC初始化调用
参数
name：ipc名称(内部管道名字)
len:name的数据长度
type：IPC类型
返回值：
0:方法调用成功
*/
IPCDLLAPI int InitIpc(const char* name, size_t len, IPC_CS_TYPE type);
  
 /*
IPC释放调用
返回值：
0:方法调用成功
*/
IPCDLLAPI int ReleaseIpc();
  
 /*
IPC发送数据调用
返回值：
>= 0:发送的字节数
< 0:方法调用失败
*/
IPCDLLAPI int SendData(const char* data, size_t len);
  
IPCDLLAPI void SetDataReceivedCallback(DataReceivedCallback cb, void* user_data);
IPCDLLAPI void SetConnectedCallback(ConnectedCallback cb, void* user_data);
IPCDLLAPI void SetDisconnectCallback(DisconnectCallback cb, void* user_data);
IPCDLLAPI void SetLogCallback(LogCallback cb, void* user_data);
}
}

# 3.1.2、c++类接入

对应头文件：ipc_i_wrapper.h

namespace kuaishou {
namespace ipc {

class IpcListener {
 public:
  virtual void OnDataReceived(const char* message, size_t len) = 0;
  virtual void OnConnected() = 0;
  virtual void OnDisconnected() = 0;
  virtual void OnLog(const char* log, size_t len) {}
  virtual ~IpcListener() {}
};

class IpcInst {
 public:
  virtual int SendData(const char* message, size_t len) = 0;
  virtual ~IpcInst() {}
};

IPCDLLAPI IpcInst* KwaiCreateIpcInst(const char* name, size_t len, IPC_CS_TYPE type, IpcListener* listener);
IPCDLLAPI void KwaiReleaseIpcInst(IpcInst* inst);
IPCDLLAPI int KwaiSendDataByInst(IpcInst* inst, const char* data, size_t len);
}
}

说明：弹幕玩法进程收到disconnect通知时，代表PC伴侣已经退出，此时弹幕玩法也应该退出。

# 3.2、业务传参说明

# 协议格式

双方以Json格式进行通信

{
    "type": "",      // 业务类型
    "data": {},      // 业务数据
    "version": 1  // 版本号，后续扩展使用
}

# 3.3、类型命名规范

命名规范主要分为三段：消息来源_消息含义_消息类型(可选)

# 消息来源

发送方

接收方

命名规范

PC直播伴侣

弹幕玩法

以SC_开头

例：SC_STARTUP

弹幕玩法

PC直播伴侣

以CS_开头

例：CS_INITED

# 消息含义

代表此消息含义，命名以简单清晰明了为主

例如：SC_STARTUP

# 消息类型

应答确认消息

其中遵循消息来源命名规范，消息含义不变，以ACK进行结尾

例：SC_STARTUP消息进行确认发送CS_STARTUP_ACK

# 3.4、业务协议

# SDK内部已实现协议(业务侧无需感知)

类型（type）	数据(data)
SC_STARTUP	{ "heartbeat_interval_ms":5000 }
CS_HEARTBEAT
SC_HEARTBEAT_ACK

# 业务侧协议(弹幕玩法方关注)

类型（type）

数据(data)

使用场景

SC_SET_CODE

{

"code":"123456"

}

弹幕玩法启动后接收匹配码

触发场景:开播前启动玩法，开播后伴侣会通过SC_SET_CODE将最新的匹配码告知玩法

SC_QUIT

{

"message"："退出原因"

}

PC直播伴侣通知弹幕玩法退出

触发场景:主播点击"重启"，对于支持ipc退出的玩法(ks_manifest.json中对用的配置项是ipcQuit)，伴侣会下发SC_QUIT

# 3.5、版本历史

版本号	更新时间	下载链接	版本内容
8fd4d4d	2023.05.12	https://d4.a.kwimgs.com/kos/nlav12667/kuaishou_ipc/ipc_8fd4d4d.rar	修改c++接口名称
78b4cb6	2023.05.05	https://d4.a.kwimgs.com/kos/nlav12667/kuaishou_ipc/ipc_78b4cb6.rar	修复ReleaseInst偶现卡死问题

# 4、玩法客户端联调

玩法开发者通过快手小程序平台 (opens new window)上传基本的物料信息、包体

具体流程如下（【弹幕类】开发者入驻小玩法操作指引 (opens new window)）

玩法包体上传进行自测

上传完毕后点击自测

Í

点击自测后在【项目成员管理】增加自测人员「体验者」权限

添加成员

输入快手号，点击确认添加，

1.添加「体验者」身份权限才能查看自测包+开通私密直播（注意：后台成员数量≦90）

2.快手账号查询方法：快手app个人主页“我”，点击右上角三个点，点击分享主页，点击生成海报，复制快手号（UID)

3.自测快手直播伴侣版本 ≥ 5.9.0.1851

完成以上步骤等待审批通过后，就能在伴侣上看到对于玩法的入口。开发者就可以按照如下步骤进行功能联调了。

以弹幕玩法appId（快手分配给开发者的玩法id）为 ks682858293699136749 为例，实际联调时替换为快手分配的appId。

第一步：点击弹幕玩法入口，找到玩法，并下载

第二步：随便打开一个文件夹，在地址栏输入%appdata%/kwailive/show_tools/ks682858293699136749后回车，打开玩法文件夹

第三步：拷贝完整玩法包到%appdata%/kwailive/show_tools/ks682858293699136749，若有同名文件选择覆盖

第四步：点击弹幕玩法入口，找到玩法，点击“打开”启动玩法

# 5、开发常见问题

# Q：创建ipc时需要的name参数哪里来？

A：启动参数-ipc。注意：须ks_manifest.json中的ipcSetCode或ipcQuit为true，伴侣会在启动玩法时增加-ipc命令行参数。

# Q：启动玩法后，很快弹窗提示切换其他玩法，如下图？

A：启动弹幕玩法后，伴侣会监听列表中的所有进程是否正在运行，如果所有的进程都不存在就会提示异常。检查ks_manifest.json中的workFileNames配置，确保包含游戏进程。

# Q：弹幕玩法直播间通过手机观看玩法画面比较模糊（相对其他弹幕玩法直播间）？

A：1、查看手机的观看分辨率，确保观看高清直播 2、调整玩法窗口大小，确保游戏区域分辨率大于1080P

# Q：弹幕玩法何时自动退出？

A：1、收到IPC的OnDisconnect消息

2、收到IPC的SC_QUIT消息

# Q：通过命令行参数（-c）已经获取到了roomCode，又再次收到来自IPC的SET_CODE消息，需要更新roomCode吗？

A：需要

# Q：启动弹幕玩法不能自动捕获是什么原因导致的？

A：请检查ks_manifest.json的capturnParam （参考快手弹幕玩法客户端接入说明 (opens new window)）

如果依然没有找到问题，请按照如下步骤反馈：
1、关闭伴侣、关闭游戏
2、手动启动玩法和PC伴侣，使用PC伴侣通过添加游戏或窗口的方式（与ks_manifest.json中的captureParam中的type一致）查看能否正常展示。
3、通过添加窗口的方式添加游戏窗口，伴侣内可以正常看到游戏画面

4、关闭伴侣

5、收集%appdata%/kwailive/basic/scenes 和游戏目录下的ks_manifest.json反馈到游戏接入群

# Q：启动弹幕玩法后提示"当前小玩法无法正常使用，S后将关闭"是什么情况？（如下图）**

A： 1、退出玩法模式，删除左上角和弹幕玩法相关的所有源。

2、可以通过调大弹幕玩法画面占直播画面的占比，确保大于60%

3、启动弹幕玩法后，玩法画面会自动添加到直播画面，无须手动添加。（手动添加也会导致该提示，请主动删除掉）

# Q：启动弹幕玩法后一直显示连接中？如下图

A：启动弹幕玩法后会自动进入连接中状态，同时伴侣会做如下检查：

监听清单文件中 launchFileName (opens new window) 和 workFileNames (opens new window) 对应的进程至少有一个在运行

若清单文件中 ipcSetCode (opens new window) 或 ipcQuit (opens new window) 任一设为true，则监听ipc的状态是否为正常连接状态

监听弹幕玩法server 与快手server的连接状态是否正常

若以上方面都正常，则进入"游戏中"状态；

同样，当处于"游戏中"状态时，以上任一不正常，也会回到"连接中"状态

# Q：不能自动捕获游戏窗口？