Skip to content

接入文档-快手小游戏

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平台

配置 UOS CDN 云服务器,没有账号可以自行注册体验(只为了打出包后续放到火山 CDN 上)

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

转化行为activeactive_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 方式

场景值列表

场景值用来描述用户进入小游戏的路径

插件下载