Appearance
接入文档-快手小游戏
DANGER
目前sdk仅支持小游戏登录(openid获取)、广告(激励视频)、统计上报、支付、分享/转发、Track统计和深度事件!!!
支持现状
目前主要是快手 App, 包括极速版
目前 Unity 快手小游戏仅支持 Android 平台,使用 Unity 最新的 Unity Instant Game 小游戏解决方案。
参考文档: 快手小游戏信息站
接入准备
动能参数
负责人:@运营同学
C#
H5动能内部appid
H5动能内部appKey
域名加白
负责人:@运营同学
C#
https://c.vigame.cn
https://p.vigame.cn
https://x.vimedia.cn
https://u.vigame.cn
https://r.vigame.cn
https://x.vigame.cn
配置登录参数
负责人:@运营同学
广告位配置
负责人:@运营同学
C#
游戏的广告位埋点
分享位配置
负责人:@运营同学
C#
游戏的分享位埋点
版权信息
不加提审被拒
按照国家政策要求以及小游戏平台规则,进入游戏加载页面需要标明软著登记号以及著作权人信息。
安全限制(必看)
游戏中有用到下面提到的内容需自行移除
出于安全性考虑,快手小游戏在沙盒环境中运行 Unity Instant Game,在该沙盒环境下,游戏对 API 的使用受到以下限制: 代码隔离 出于安全性考虑,游戏应该只使用 Unity 提供的跨平台接口开发游戏,不应该使用任何方式调用平台特定接口(如 Android 权限获取, 文件操作等)
- 游戏不能以任何方式引入 java 代码,不能通过任何方式(包括但不限于 C# 的 AndroidJNI 类, native 方式调用 JNI) 调用自定义 java 代码。 文件系统隔离 出于安全性考虑,在快手小游戏环境下,Unity 提供的文件操作接口(包括但不限于 System.IO.File) 只能操作特定目录下的文件,Unity Instant Game 提供获取沙盒路径的接口,详情见: Unity Instant Game 沙盒路径接口。 除 Unity 接口外,不应该使用其他方式直接操作文件。
- 只使用 Unity 提供的 c# 接口(如:System.IO.File) 执行文件操作且文件路径限定在平台沙盒路径下。
- 使用 native plugin 时,plugin 中不能包括文件操作。
如果游戏违反以上安全限制,快手小游戏平台会拒绝游戏上架。
转快手小游戏
以下是 Unity 2019.4.29f1c110 版本示例
Unity下载
DANGER
注:版本并不局限于 Unity 2019.4.29f1c110,只要是支持 InstantGame 并且提供 AndroidPlayer 的版本都可以。
Instant Game Package 安装
非强制安装0.3.1版本
使用 AutoStreaming 功能需要配合 Unity Instantgame Package 使用。请在 Unity PackageManager 中,选择Unity Registry 并勾选 Show preview packages , 然后搜索 instant game , 点击“install”安装以下 package 最新版本:

如果在 PackageManager 中无法搜索到,请在项目的 Packages/manifest.json 文件中直接添加以下 package:
C#
"com.unity.instantgame": "0.3.1"
工程转换
DANGER
导入Wb插件到 Unity 工程中,并添加 KS_MINI_GAME 宏定义!!!
参考文档
1. 工程配置
- 如果il2cpp游戏首包超过20M,可以尝试开启stripEngineCode,可减少首包约3M左右,但strip后的引擎文件不再共享。
- 非字节平台可选择使用Mono打包(2021.2.5f1c303可能会报错需选择il2cpp打包),Instant Game支持64位Mono,并且大多数情况下首包相比il2cpp更小。


DANGER
注意:
- Unity 高版本 Mono 方式会有问题可以选择 IL2Cpp 方式。
- .Net 建议选择 2.x 版本使用其他版本可能报错!
2. 打开Instant Game 界面 切换到Cfg & Publish窗口,勾选 Use AutoStreaming 和 Use Font Streaming 切换到KWai平台

3. 配置Texture Streaming
首次打包操作流程:点击 convertLegacySpritePacker(可选) → Sync Texture → Ctrl + A 选择所有图片,勾选 Placeholder → 点击 Generate AssetBundles → 点击表头按生成的AB大小排序,取消勾选 AB 过小的图片(例如小 5KB,可按住Shift多选)→ 点击 Generate AssetBundles 清理不需要的AB → 点击 Generate Placeholders。 更新操作流程: Sync Texture → 调整Placeholder的勾选 → 勾选Force Rebuild → 点击 Generate AssetBundles重新生成AB → 点击 Generate Placeholders。
4. 配置Audio/Mesh/Animation Streaming
点击 Sync Audios/Meshes/Animation → 勾选 RT Mem 较大(例如大于5K)的资源
5. 场景Streaming
Sync Scenes → 选择需要streaming的场景 → Sync SharedAssets → 勾选SharedAssets资源 → 如果已经生成过场景AB,勾选Force Rebuild → Generate AssetBundles。 (推荐)切换图形API到GLES 3, 在Project Settings → Player → Other Settings中取消Auto Graphics API,仅保留GLES 3,从而减少首包和下载的云资源。 该步骤可能花费较长的时间,请耐心等待。
6. 切换到Cfg & Publish窗口 依次点击Build Instant Game和Upload to Uos CDN
其中AutoStreaming文件,需要被引擎直接使用,只能存放在UOS CDN上。

生成文件如下

7. 扫码体验快手小游戏
- 参考 快手小游戏开发者工具 使用指南,下载安装快手小游戏开发者工具,创建一个 Unity Instant Game 工程,然后将上述步骤中导出的 ig_kwai.json 文件放入工程目录。

- 点击 "真机预览" Button, 生成预览二维码,安卓手机使用最新版快手 App 扫描生成的二维码,预览小游戏运行效果。

- 确认预览结果无误后,点击 "上传" Button, 提交游戏以供审核。
初始化(必接)
DANGER
用户切换快手账号后游戏可根据openid是否变化,确定是否清空本地缓存sdk不再处理!!!
接口
csharp
/// <summary>
/// 快手小游戏sdk初始化
/// </summary>
/// <param name="appid">H5动能内部appid</param>
/// <param name="appKey">H5动能内部appKey</param>
/// <param name="callBack">初始化回调bool:是否初始化成功;string:openId;string:userCode</param>
/// <param name="payRate">根据小游戏平台配置支付时设置的支付比例(1:1、1:10、1:100)确认传1、10、100(未接支付随便填写)</param>
/// <param name="isRelax">是否为超休闲游戏,超休本地获取openid后不会再重新请求</param>
public void KsInit(string appid, string appKey, Action<bool, string, string> callBack , MiniPayRate payRate = MiniPayRate.Shi, bool isRelax = true)
示例
DANGER
接入时H5动能appid和H5动能appkey需改为正式参数!!!
csharp
Wb.CoreManager.Instance.KsInit(您的H5动能appid, 您的H5动能appkey, (ret, openId, userCode) =>
{
KS.Log("DNSDK: ======== 收到sdk初始化回调 openId: " + openId + ", userCode: " + userCode + ", result: " + ret);
if(ret)
{
// 初始化成功
// 游戏将openid保存本地用于比对玩家是否切换了快手账号
} else
{
// 初始化失败
}
}, MiniPayRate.Shi, true);
统计(必接)
根据统计埋点文件使用合适接口上报游戏中产生的事件。
DANGER
转化行为active
和active_register
事件必接!!!
1. 自定义事件(必接)
接口说明
csharp
public void TJCustomEvent(string eventId)
public void TJCustomEvent(string eventId, string label)
public void TJCustomEvent(string eventId, Dictionary<string, string> attributes)
事件说明
事件名称 | 事件ID | 触发时机 | 附加参数 |
游戏loading页面 | app_loading_show | 游戏引擎初始化后就触发上报 | 无 |
游戏内首页 | app_home_show | 主页展示时 | 无 |
使用示例
csharp
//示例
Wb.TjManager.Instance. TJCustomEvent("app_loading_show");
Wb.TjManager.Instance. TJCustomEvent("app_home_show");
2. 转化行为上报(必接)
WARNING
注意:转化行为上报使用TjSendTrackingEvent
接口!!!
SDK会本地缓存埋点记录,再上报会进行拦截
接口说明
csharp
/// <summary>
/// 转化行为上报
/// </summary>
/// <param name="eventId">事件id</param>
/// <param name="val">额外参数json字符串</param>
public void TjSendTrackingEvent(string eventId, string val = "")
事件id | 事件定义 | data额外携带数据 | 建议上报时机 |
---|---|---|---|
active(自实现上报必接) | 激活 | 首次进入主页触发 | |
active_register(自实现上报必接) | 注册 | 完成角色创建后触发。如果没有角色创建过程,可跟active事件同时触发。 |
使用示例
csharp
Wb.TjManager.Instance.TjSendTrackingEvent("active");
Wb.TjManager.Instance.TjSendTrackingEvent("active_register");
3.关卡统计上报(必接)
接口说明
csharp
/// <summary>
/// 关卡开始
/// </summary>
/// <param name="level">关卡id</param>
public void StartLevel(string level)
/// <summary>
/// 关卡获胜
/// </summary>
/// <param name="level">关卡id</param>
/// <param name="score">得分</param>
public void FinishLevel(string level, string score)
/// <summary>
/// 关卡失败
/// </summary>
/// <param name="level">关卡id</param>
/// <param name="score">得分</param>
public void FailLevel(string level, string score)
事件说明
事件id | 事件定义 | data额外携带数据 | 建议上报时机 |
---|---|---|---|
begin | 开始 | levelid:关卡ID | 进入关卡 |
complete | 胜利 | levelid:关卡IDscore:得分 | 关卡胜利 |
fail | 失败 | levelid:关卡IDscore: 得分 | 关卡失败 |
使用示例
csharp
Wb.TjManager.Instance.StartLevel("3-1");
Wb.TjManager.Instance.FinishLevel("3-1", "100");
Wb.TjManager.Instance.FailLevel("3-1", "100");
4.用户行为统计上报
事件id | 事件定义 | data额外携带数据 | 建议上报时机 |
---|---|---|---|
online | 在线时长 | duration--时长(秒) | 用户切到后台或者杀掉进程时 |
setting_page_click | 设置页点击 | button_click:1用户反馈,2游戏圈,3微信客服 | 设置页内点击按钮时(用户反馈,游戏圈、微信客服) |
self_button_click | 大厅内点击 | button:1-点击购物车,2-点击跳转合成界面,3-点击任务栏,4-点击能量弹窗(各游戏需要自己定义数值) | 大厅界面点击按钮时 |
5.分享/邀请统计上报
事件id | 事件定义 | data额外携带数据 | 建议上报时机 | |
---|---|---|---|---|
分享 | help_share | 分享小程序 | 分享小程序到会话时 | |
help_button_click | 点击求助好友按钮 | bonus_status:1领取成功,2领取失败 help_times_left: 剩余领取次数1,2,3 | 点击求助好友按钮时 | |
邀请 | invite_click | 点击邀请好友入口 | invite_number:邀请好友的数量 0,1,2... | 玩家在主页点击邀请好友入口时上报 (首次弹出时上报0) |
invite_click_plus | 点击加号邀请好友 | / | 玩家在邀请好友界面点击加号时 | |
bonus_click | 点击领取奖励 | bonus_status:1领取成功,2领取失败 | 点击领取奖励时 |
6.设置关卡和活动进度
WARNING
sdk
上报stay_time
事件时会携带下面设置的数据
接口说明
csharp
/// <summary>
/// 设置上报level_id参数
/// </summary>
/// <param name="levelId"></param>
public void SetTjLevelId(string levelId)
/// <summary>
/// 设置上报活动进度参数
/// </summary>
/// <param name="json">活动json格式的字符串</param>
public void SetTjActivityProgress(string json)
使用示例
csharp
Wb.TjManager.Instance.SetTjLevelId("10");
Wb.TjManager.Instance.SetTjActivityProgress("{\"activity_id\":10,\"activity_progress\":15,\"activity_bonus_id\":15,\"begain_time\":100,\"valid_time\":120}");
7.设置用户标识
WARNING
调用下面接口设置后,所有事件上报都会携带用户id
csharp
/// <summary>
/// 设置用户id
/// </summary>
/// <param name="userId">用户id</param>
public void SetLoginId(string userId)
使用示例
csharp
Wb.CoreManager.Instance.SetLoginId("123321");
广告(必接)
1. 打开广告
csharp
/// <summary>
/// 打开广告
/// </summary>
/// <param name="adName">广告位名称</param>
/// <param name="callBackFun">广告关闭回调,状态0成功、1失败、2加载失败</param>
/// <param name="adStartFun">广告播放状态回调,小游戏不要使用</param>
public void OpenAd(string adName, ADCallback callBackFun = null, AdStartCallback adStartFun = null)
示例
csharp
Wb.ADManager.Instance.OpenAd("home_mfzs", (ret, info) => {
if (ret == ADResult.Success)
{
Debug.Log("Unity: 广告打开成功 OpenAdTest VideoAd info = " + info);
}
else
{
Debug.Log("Unity: 广告打开失败 OpenAdTest VideoAd info = " + info);
}
});
2. 广告是否缓存好
广告为实时加载方式(不缓存广告),调用接口直接返回true
csharp
/// <summary>
/// 广告是否缓存好
/// </summary>
/// <param name="adName">广告位名称</param>
public bool IsAdReady(string adName)
3. 某关卡是否可以打开该广告
csharp
/// <summary>
/// 某关卡是否可以打开该广告
/// </summary>
/// <param name="adName">广告位名称</param>
/// <param name="level">关卡id</param>
public bool IsAdBeOpenInLevel(string adName, int level)
4. 关闭广告
csharp
/// <summary>
/// 关闭广告
/// </summary>
/// <param name="adName">广告位名称</param>
public void CloseAd(string adName)
支付
目前仅支持Android平台,SDK插件v2.3.2版本开始支持。
1.支付
WARNING
注意:PayParam 充值金额单位为分,如1元需要传入100。
接口说明
c
/// <summary>
/// 小游戏支付
/// </summary>
/// <param name="ver">小游戏支付版本(仅微小有效),1:虚拟支付1.0版; 2:虚拟支付2.0版</param>
/// <param name="payParam">支付参数</param>
/// <param name="rate">根据小游戏平台配置支付时设置的支付比例(1:1、1:10、1:100)确认传1、10、100</param>
/// <param name="callFun"></param>
public void MiniPay(MiniPayVer ver, PayParam payParam, OrderPayCallbackHandler callFun = null)
示例
c
var dic = new Dictionary<string, object>
{
{ "offer_wave", 100 },
{ "active_coin", 9999 }
};
var payParam = new Wb.PayParam(1, 100, "新手礼包"); // 具体参数可查看PayParam类说明
payParam.SetGiftNum(1);
payParam.SetTokenType("10");
payParam.SetGiftType("diamond");
payParam.SetLevelId("lv_1");
payParam.SetUserId("userid_1001");
payParam.SetPayPush("1");
payParam.SetCustom("透传参数");
payParam.SetExtraParam(dic);
Wb.PayManager.Instance.MiniPay(Wb.MiniPayVer.ver2, payParam, (result, payId, userData, orderId) => {
Debug.Log("PayManager payId = " + payId);
Debug.Log("PayManager orderId = " + orderId);
Debug.Log("PayManager userData = " + userData);
switch (result)
{
case Wb.PayStatus.PaySuccess:
Debug.Log("PayManager 支付成功");
Debug.Log("PayManager MiniPay 充值到账上报");
Wb.TjManager.Instance.TjPayOnAccount(orderId);
break;
case Wb.PayStatus.PayFail:
Debug.Log("PayManager 支付失败");
break;
case Wb.PayStatus.PayCancel:
Debug.Log("PayManager 支付取消");
break;
case Wb.PayStatus.PayNetError:
Debug.Log("PayManager 支付完成,遇到网络问题,请重新消耗订单");
break;
default:
Debug.Log("PayManager 支付失败");
break;
}
});
2.补单
适用场景:使用sdk支付,非服务器发奖
设置补单回调
c
/// <summary>
/// 设置补单回调
/// 调用该接口会触发sdk补单流程
/// 根据实际情况确认调用时机
/// </summary>
/// <param name="callFun">支付回调</param>
public void SetInventoryCallBack(OrderPayCallbackHandler callFun)
示例
c
Wb.PayManager.Instance.SetInventoryCallBack((payStatus, payId, userData, orderId) =>
{
Debug.Log("PayManager payId = " + payId);
Debug.Log("PayManager orderId = " + orderId);
Debug.Log("PayManager userData = " + userData);
switch (payStatus)
{
case Wb.PayStatus.PaySuccess:
Debug.Log("支付成功");
Debug.Log("PayManager SetInventoryCallBack 充值到账上报");
Wb.TjManager.Instance.TjPayOnAccount(orderId);
break;
case Wb.PayStatus.PayFail:
Debug.Log("支付失败");
break;
case Wb.PayStatus.PayCancel:
Debug.Log(""支付取消");
break;
case Wb.PayStatus.PayNetError:
Debug.Log(""网络错误,需做补单处理");
break;
default:
Debug.Log(""未知错误");
break;
}
});
3.支付到账上报
适用场景:使用sdk支付,支付成功下发奖励后调用,非服务器发奖
c
/// <summary>
/// 支付到账上报
/// </summary>
/// <param name="orderId">订单号</param>
public void TjPayOnAccount(string orderId)
分享
分享策略名称由策划或运营提供。
1.主动分享
c
/// <summary>
/// 小游戏-主动分享接口
/// </summary>
/// <param name="shareName">分享策略名称</param>
/// <param name="userData">自定义数据使用'&'拼接</param>
public void ShareAppMessage(string shareName, string userData = "")
//调用示例
Wb.SocialManager.Instance.ShareAppMessage("分享策略名称", "t1=1&t2=2");
兑换码
1. 兑换码开关
通过游戏在线参数配置InitGameConfig获取兑换码开关!!! 自定义配置参数 key:dhm
2.使用兑换码
c
/// <summary>
/// 使用兑换码
/// </summary>
/// <param name="dhm">兑换码id</param>
/// <param name="callFun">回调:</param>
public void UseCDKey(string dhm, Action<CDKeyState, string, string> callFun)
兑换码状态
c
// 兑换码状态
public enum CDKeyState
{
Success = 200, // 成功
ParamError = 401, // param is error 参数验证不通过
UnOperate = 402, // 无效操作
Invalid = 403, // 兑换码无效
Used = 405, // 兑换失败,当前兑换码已经被使用过了
UnUse = 406, // 当前兑换码已经失效
Repeat = 407, // 不能重复使用
UnExist = 408, // 兑换码不存在
Busy = 505, // 系统繁忙
}
示例
c
Wb.CoreManager.Instance.UseCDKey("兑换码", (state, value, msg)=>{
if(Wb.CDKeyState.Success == state) {
// CDKey Success value = {"test":"11","te":"22"} msg = 兑换成功
// Debug.Log("CDKey Success value = " + value + " msg = " + msg);
} else {
// Debug.Log("CDKey Fail value = " + value + " msg = " + msg);
}
});
回调value示例
生成兑换码时配置了如下格式的value,兑换成功将下发配置的value
json
{
"rewards": [
{
"type": 1,
"name": "钞票",
"num": 5
},
{
"type": 2,
"name": "票券",
"num": 10
}
]
}
3.获取兑换码信息
获取接口和现有使用兑换码接口返回的数据一致,只是不会消耗兑换码
c
/// <summary>
/// 获取兑换码信息
/// </summary>
/// <param name="dhm">兑换码</param>
/// <param name="callFun"></param>
public void GetCDKeyInfo(string dhm, Action<CDKeyState, string, string> callFun)
兑换码状态
c
// 兑换码状态
public enum CDKeyState
{
Success = 200, // 成功
ParamError = 401, // param is error 参数验证不通过
UnOperate = 402, // 无效操作
Invalid = 403, // 兑换码无效
Used = 405, // 兑换失败,当前兑换码已经被使用过了
UnUse = 406, // 当前兑换码已经失效
Repeat = 407, // 不能重复使用
UnExist = 408, // 兑换码不存在
Busy = 505, // 系统繁忙
}
示例
c
Wb.CoreManager.Instance.GetCDKeyInfo("兑换码", (state, value, msg) => {
//Debug.Log("CDKey info value = " + value + " msg = " + msg);
});
回调value示例
生成兑换码时配置了如下格式的value,查询成功将下发配置的value
json
{
"rewards": [
{
"type": 1,
"name": "钞票",
"num": 5
},
{
"type": 2,
"name": "票券",
"num": 10
}
]
}
游戏在线参数配置
1. 获取游戏在线参数
c
/// <summary>
/// 获取游戏在线参数
/// </summary>
/// <param name="version">配置版本: 填写1即可</param>
/// <param name="callFun">回调</param>
public void InitGameConfig(int version, GameConfigCallback callFun)
示例
c
Wb.CoreManager.Instance.InitGameConfig(1, (result) => {
//ture获取成功;false失败
if (result)
{
//获取成功
var dhm = Wb.CoreManager.Instance.GetConfigValue("dhm");
// 兑换码自定义配置参数 key:dhm,默认开启,0是关闭,1是开启
if(dhm.Equals("0"))
{
// 关闭兑换码功能
}
else
{
// 开启兑换码功能
}
}
else
{
//获取失败,则使用默认值处理逻辑
}
}
2.根据key获取value
c
/// <summary>
/// 根据key获取参数
/// </summary>
/// <param name="key">关键字</param>
/// <returns>参数值</returns>
public string GetConfigValue(string key)
示例
c
//根据配置的关键字获取value;获取为空串,表示没有该配置或者key不对。
string str = Wb.CoreManager.Instance.GetConfigValue("key");
隐私政策
自测标准(必看)
严格按要求测试,否则审核被拒
常见问题总汇
注:2021.2.5f1c303 Mono 方式报如下错误需使用 IL2CPP 方式

场景值列表
插件下载
快手插件 前往接入文档下载最新版本插件
动能插件 Unity插件-小游戏版