接入文档-快手小游戏

目前sdk仅支持小游戏登录（openid获取）、广告（激励视频）、统计上报、分享/转发、Track统计和深度事件！！！

支持现状

目前主要是快手 App， 包括极速版

目前 Unity 快手小游戏仅支持 Android 平台，使用 Unity 最新的 Unity Instant Game 小游戏解决方案。

参考文档： 快手小游戏信息站

接入准备

动能参数

负责人：@运营同学

H5动能内部appid
H5动能内部appKey

域名加白

负责人：@运营同学

https://c.vigame.cn
https://p.vigame.cn
https://x.vimedia.cn
https://u.vigame.cn
https://r.vigame.cn
https://x.vigame.cn

配置登录参数

负责人：@运营同学

广告位配置

负责人：@运营同学

游戏的广告位埋点

分享位配置

负责人：@运营同学

游戏的分享位埋点

版权信息

不加提审被拒

按照国家政策要求以及小游戏平台规则，进入游戏加载页面需要标明软著登记号以及著作权人信息。

安全限制（必看）

游戏中有用到下面提到的内容需自行移除

出于安全性考虑，快手小游戏在沙盒环境中运行 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下载

注：版本并不局限于 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:

"com.unity.instantgame": "0.3.1"

工程转换

导入Wb插件到 Unity 工程中，并添加 KS_MINI_GAME 宏定义！！！

参考文档

1. 工程配置

  • 如果il2cpp游戏首包超过20M，可以尝试开启stripEngineCode，可减少首包约3M左右，但strip后的引擎文件不再共享。

  • 非字节平台可选择使用Mono打包（2021.2.5f1c303可能会报错需选择il2cpp打包），Instant Game支持64位Mono，并且大多数情况下首包相比il2cpp更小。

注意：

  • 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, 提交游戏以供审核。

初始化（必接）

用户切换快手账号后游戏可根据openid是否变化，确定是否清空本地缓存sdk不再处理！！！

接口

/// <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)

示例

接入时H5动能appid和H5动能appkey需改为正式参数！！！

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);

统计（必接）

根据统计埋点文件使用合适接口上报游戏中产生的事件。

转化行为active和active_register事件必接！！！

1. 自定义事件（必接）

接口说明

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

主页展示时

无

使用示例

//示例
Wb.TjManager.Instance. TJCustomEvent("app_loading_show")；
Wb.TjManager.Instance. TJCustomEvent("app_home_show")；

2. 转化行为上报（必接）

注意：转化行为上报使用TjSendTrackingEvent接口！！！ SDK会本地缓存埋点记录，再上报会进行拦截

接口说明

/// <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事件同时触发。

使用示例

Wb.TjManager.Instance.TjSendTrackingEvent("active")；
Wb.TjManager.Instance.TjSendTrackingEvent("active_register")；

3.关卡统计上报（必接）

接口说明

/// <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: 得分

关卡失败

使用示例

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.设置关卡和活动进度

sdk上报stay_time事件时会携带下面设置的数据

接口说明

/// <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)

使用示例

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.设置用户标识

调用下面接口设置后，所有事件上报都会携带用户id

/// <summary>
/// 设置用户id
/// </summary>
/// <param name="userId">用户id</param>
public void SetLoginId(string userId)

使用示例

Wb.CoreManager.Instance.SetLoginId("123321");

广告（必接）

1. 打开广告

/// <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)

示例

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

/// <summary>
/// 广告是否缓存好
/// </summary>
/// <param name="adName">广告位名称</param>
public bool IsAdReady(string adName)

3. 某关卡是否可以打开该广告

/// <summary>
/// 某关卡是否可以打开该广告
/// </summary>
/// <param name="adName">广告位名称</param>
/// <param name="level">关卡id</param>
public bool IsAdBeOpenInLevel(string adName, int level)

4. 关闭广告

/// <summary>
/// 关闭广告
/// </summary>
/// <param name="adName">广告位名称</param>
public void CloseAd(string adName)

分享

分享策略名称由策划或运营提供。

1.主动分享

/// <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");

隐私政策

小游戏不可添加单独的隐私协议

自测标准（必看）

严格按要求测试，否则审核被拒

自测标准

常见问题总汇

快手小游戏常见问题总汇

注：2021.2.5f1c303 Mono 方式报如下错误需使用 IL2CPP 方式

场景值列表

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

插件下载

Previous接入文档-抖音小游戏NextSDK下载

Last updated