快手小游戏接口上报文档
<p>[TOC]</p>
<h1>注意</h1>
<p><div style="background: #fda7b4;padding: 12px; border-radius: 8px; color: #000;">1、快手小游戏接口上报，无法使用js SDK的可使用
2、如果能使用js SDK接入，建议接入[抖音小游戏SDK文档](<a href="https://cps.moyangmoyang.com/b6791bnlwiki/douyin">https://cps.moyangmoyang.com/b6791bnlwiki/douyin</a> "抖音小游戏SDK文档")
</div></p>
<h1>介绍</h1>
<p><div style="background: #9efca6;padding: 12px; border-radius: 8px; color: #000;">抖音小游戏CPS上报接口。
接入前需要运营先在CPS后台添加对应的游戏appid，提供生成加密密钥 secret_key，研发才能进行后续接入。</p>
<p>接口主域名为 <code>https://cps.moyangmoyang.com</code></p>
<p>全部采用POST请求，请求必须有加密签名，支持JSON和表单格式
</div></p>
<h1>签名加密</h1>
<pre><code>1）参数名进行升序排序后
2）md5(源字符串+&#039;&amp;secret_key=&#039;+secret_key)生成签名sign
3) 生成的签名小写，无需转换
提供加密代码实例：
PHP：
ksort($data);
$tmp=array();
foreach ($data as $k =&gt; $v) {
$tmp[] = $k . &#039;=&#039; . $v;
}
$str = implode(&#039;&amp;&#039;, $tmp) . &#039;&amp;secret_key=&#039;.$secret_key;
$realSign = md5($str);
return $realSign;
js：
function check_sign(data, secret_key) {
let keys = Object.keys(data);
keys.sort();
let tmp = [];
for (let i = 0; i &lt; keys.length; i++) {
tmp.push(keys[i] + &#039;=&#039; + data[keys[i]]);
}
console.log(tmp.join(&#039;&amp;&#039;));
let str = tmp.join(&#039;&amp;&#039;) + &#039;&amp;secret_key=&#039; + secret_key;
let sign = md5(str);
console.log(sign);
}</code></pre>
<h1>1.上报注册用户信息（必须，首先上报）</h1>
<p><div style="background: #fda7b4;padding: 12px; border-radius: 8px; color: #000;">⚡ <strong>注意</strong>
必须上报，必须首先上报这个
</div></p>
<h2>1.1接口说明</h2>
<p><div style="background: #9efca6;padding: 12px; border-radius: 8px; color: #000;">✍上报第一次进入游戏的新用户，account_id和其他信息</p>
<p><code>url:</code>
<code>https://cps.moyangmoyang.com/api/ksgame/userinfo</code>
</div>
<div style="background: #FFE4B5;padding: 12px; border-radius: 8px; color: #000;">⚠️ <strong>注意</strong>
后续接口依赖于已存在的用户数据，所以此接口必须先完成上报才能接入后续上报
</div></p>
<h2>1.2参数说明</h2>
<p>|参数名|必选|类型|说明|
|:---- |:---|:----- |----- |
|account_id |是 |string |玩家openid：小游戏服务器从快手服务器获取 |
|game_appid |是 |string | 游戏appid |
|channel_id |是 |string | ksgame |
|sub_channel_id |是 |string | 通过 [ks.getLaunchOptionsSync](<a href="https://ks-game-docs.kuaishou.com/minigame/api/base/lifecycle/ks.getLaunchOptionsSync.html">https://ks-game-docs.kuaishou.com/minigame/api/base/lifecycle/ks.getLaunchOptionsSync.html</a> "ks.getLaunchOptionsSync")里面的 query 字段获取到链接上的<strong>creative_id</strong>，<span style="color:red">空的话默认：test_sub_channel_id</span>>>>>>>字段详情看备注 |
|callback |是 |string | 通过 [ks.getLaunchOptionsSync](<a href="https://ks-game-docs.kuaishou.com/minigame/api/base/lifecycle/ks.getLaunchOptionsSync.html">https://ks-game-docs.kuaishou.com/minigame/api/base/lifecycle/ks.getLaunchOptionsSync.html</a> "ks.getLaunchOptionsSync") 里面的 query 字段获取到链接上的<strong>callback</strong>，<span style="color:red">空的话默认：传空</span>>>>>>> 字段详情看备注 |
|dyadid |是 |string | 通过 [ks.getLaunchOptionsSync](<a href="https://ks-game-docs.kuaishou.com/minigame/api/base/lifecycle/ks.getLaunchOptionsSync.html">https://ks-game-docs.kuaishou.com/minigame/api/base/lifecycle/ks.getLaunchOptionsSync.html</a> "ks.getLaunchOptionsSync") 里面的 query 字段获取到链接上的<strong>dyadid</strong>，<span style="color:red">空的话默认：传空</span>>>>>>> 字段详情看备注 |
|shareid |是 |string | 通过哪个用户的分享进来，分享用户的account_id,没有传0 |
|sign |是 |string | 生成签名 |</p>
<p><strong>字段备注</strong>
获取启动参数示例：
C#：[获取启动参数](<a href="https://docs.qingque.cn/d/home/eZQBKPPXInAfG7EKhBVmCzYhC?identityId=1oE3XPpOoOC#section=h.djq3q8x0qdfh">https://docs.qingque.cn/d/home/eZQBKPPXInAfG7EKhBVmCzYhC?identityId=1oE3XPpOoOC#section=h.djq3q8x0qdfh</a> "获取启动参数")
Js：[获取启动参数](<a href="https://ks-game-docs.kuaishou.com/minigame/api/base/lifecycle/ks.getLaunchOptionsSync.html">https://ks-game-docs.kuaishou.com/minigame/api/base/lifecycle/ks.getLaunchOptionsSync.html</a> "获取启动参数")</p>
<p>sub_channel_id字段详情：开发人员可以通过[ks.getLaunchOptionsSync](<a href="https://ks-game-docs.kuaishou.com/minigame/api/base/lifecycle/ks.getLaunchOptionsSync.html">https://ks-game-docs.kuaishou.com/minigame/api/base/lifecycle/ks.getLaunchOptionsSync.html</a> "ks.getLaunchOptionsSync") 里面的 query 字段获取到链接上的<span style="color:red"><strong>creative_id</strong></span>参数。<strong>只有通过广告进来的用户，query中才会有creative_id参数</strong>，空的话默认test_sub_channel_id</p>
<p>callback字段详情：开发人员可以通过 [ks.getLaunchOptionsSync](<a href="https://ks-game-docs.kuaishou.com/minigame/api/base/lifecycle/ks.getLaunchOptionsSync.html">https://ks-game-docs.kuaishou.com/minigame/api/base/lifecycle/ks.getLaunchOptionsSync.html</a> "ks.getLaunchOptionsSync")里面的 query 字段获取到链接上的<span style="color:red"><strong>callback</strong></span>参数。<strong>只有通过广告进来的用户，query中才会有callback参数</strong>，空的话默认就传空</p>
<p>dyadid字段详情：开发人员可以通过 [ks.getLaunchOptionsSync](<a href="https://ks-game-docs.kuaishou.com/minigame/api/base/lifecycle/ks.getLaunchOptionsSync.html">https://ks-game-docs.kuaishou.com/minigame/api/base/lifecycle/ks.getLaunchOptionsSync.html</a> "ks.getLaunchOptionsSync") 里面的 query 字段获取到链接上的<span style="color:red"><strong>dyadid</strong></span>参数。<strong>只有通过广告进来的用户，query中才会有dyadid参数</strong>，空的话默认就传空</p>
<p><div style="background: #9efca6;padding: 12px; border-radius: 8px; color: #000;">query中creative_id和callback参数示例：👇👇👇👇👇
</div></p>
<p><img src="https://www.showdoc.com.cn/server/api/attachment/visitFile?sign=e8807a2ffdbee70c5f94600136d2641a&amp;file=file.png" alt="" /></p>
<h2>1.3示例代码</h2>
<p>示例密钥：T1yO6JUDnVZDUt2k7649Vb</p>
<pre><code class="language-javascript">{
&quot;account_id&quot;: &quot;34D015FCDA78A87A07FA5CF3B5276523&quot;,
&quot;game_appid&quot;: &quot;ks123456789&quot;,
&quot;channel_id&quot;: &quot;ksgame&quot;,
&quot;sub_channel_id&quot;: &quot;test_ sub_channel_id&quot;,
&quot;callback&quot;: &quot;&quot;,
&quot;shareid&quot;: &quot;0&quot;,
&quot;dyadid&quot;: &quot;&quot;,
&quot;sign&quot;: &quot;bd1a444d919bfcf92a50b0427dafaaca&quot;
}</code></pre>
<h2>1.4接口返回</h2>
<pre><code class="language-javascript">Callback: {&quot;code&quot;:1,&quot;msg&quot;:&quot;用户已经上报&quot;,&quot;time&quot;:&quot;1721272806&quot;,&quot;data&quot;:null}</code></pre>
<h1>2.登陆活跃信息上报（必须）</h1>
<h2>2.1接口说明</h2>
<p><div style="background: #9efca6;padding: 12px; border-radius: 8px; color: #000;">✍用户每次打开登陆游戏时候上报</p>
<p><code>url:</code>
<code>https://cps.moyangmoyang.com/api/ksgame/login</code>
</div>
<div style="background: #FFE4B5;padding: 12px; border-radius: 8px; color: #000;">⚠️ <strong>注意</strong>
如果是当天注册的新用户，只需上报注册信息即可，无需再调用此接口
</div></p>
<h2>2.2参数说明</h2>
<p>|参数名|必选|类型|说明|
|:---- |:---|:----- |----- |
|game_appid |是 |string |游戏appid |
|channel_id |是 |string | ksgame |
|sub_channel_id |是 |string | 通过 [ks.getLaunchOptionsSync](<a href="https://ks-game-docs.kuaishou.com/minigame/api/base/lifecycle/ks.getLaunchOptionsSync.html">https://ks-game-docs.kuaishou.com/minigame/api/base/lifecycle/ks.getLaunchOptionsSync.html</a> "ks.getLaunchOptionsSync")里面的 query 字段获取到链接上的<strong>creative_id</strong>，<span style="color:red">空的话默认：test_sub_channel_id</span> |
|account_id |是 |string | 玩家openid：小游戏服务器从快手服务器获取 |
|sign |是 |string | 生成签名 |</p>
<h2>2.3示例代码</h2>
<pre><code class="language-javascript">{
&quot;account_id&quot;: &quot;34D015FCDA78A87A07FA5CF3B5276523&quot;,
&quot;game_appid&quot;: &quot;ks123456789&quot;,
&quot;channel_id&quot;: &quot;ksgame&quot;,
&quot;sub_channel_id&quot;: &quot;12313131001&quot;,
&quot;sign&quot;: &quot;c57854337929ae7cb1c97b432fc319d74ad817ca&quot;
}</code></pre>
<h2>2.4接口返回</h2>
<pre><code class="language-javascript">Callback: {&quot;code&quot;:0,&quot;msg&quot;:&quot;登录已上报&quot;,&quot;time&quot;:&quot;1724053440&quot;,&quot;data&quot;:null}</code></pre>
<h1>3.创建角色信息上报</h1>
<h2>3.1接口说明</h2>
<p><div style="background: #9efca6;padding: 12px; border-radius: 8px; color: #000;">✍上报创角事件</p>
<p><code>url:</code>
<code>https://cps.moyangmoyang.com/api/ksgame/create_role</code>
</div></p>
<h2>3.2参数说明</h2>
<p>|参数名|必选|类型|说明|
|:---- |:---|:----- |----- |
|role_id |是 |string |角色ID （若无角色唯一id，则传account_id） |
|nickname |是 |int | 角色名称 |
|server_id |是 |int | 区服ID，没有填个默认数字 |
|server_name |是 |string | 区服名称，没有填个默认名称 |
|game_appid |是 |string | 游戏appid |
|account_id |是 |string | 玩家openid：小游戏服务器从快手服务器获取 |
|sign |是 |string | 生成签名 |</p>
<h2>3.3示例代码</h2>
<pre><code class="language-javascript">{
&quot;account_id&quot;: &quot;34D015FCDA78A87A07FA5CF3B5276523&quot;,
&quot;game_appid&quot;: &quot;ks123456789&quot;,
&quot;role_id&quot;: &quot;100001&quot;,
&quot;nickname&quot;: &quot;测试角色&quot;,
&quot;server_id&quot;: &quot;1&quot;,
&quot;server_name&quot;: &quot;测试&quot;,
&quot;sign&quot;: &quot;bd28fd121a154147bd1405ac8377c4410df4f817&quot;
}</code></pre>
<h2>3.4接口返回</h2>
<pre><code class="language-javascript">Callback: {&quot;code&quot;:1,&quot;msg&quot;:&quot;成功&quot;,&quot;time&quot;:&quot;1721272731&quot;,&quot;data&quot;:null}</code></pre>
<h1>4.激励视频广告点击（有激励视频必须上报）</h1>
<h2>4.1接口说明</h2>
<p><div style="background: #9efca6;padding: 12px; border-radius: 8px; color: #000;">✍激励视频广告点击上报</p>
<p><code>url:</code>
<code>https://cps.moyangmoyang.com/api/ksgame/video_click</code>
</div>
<div style="background: #FFE4B5;padding: 12px; border-radius: 8px; color: #000;">⚠️ <strong>注意</strong>
1.只上报激励视频
2.广告show出来的时候上报
</div></p>
<h2>4.2参数说明</h2>
<p>|参数名|必选|类型|说明|
|:---- |:---|:----- |----- |
|game_appid |是 |string | 游戏appid |
|account_id |是 |string | 玩家openid：小游戏服务器从快手服务器获取 |
|sign |是 |string | 生成签名 |</p>
<h2>4.3示例代码</h2>
<pre><code class="language-javascript">{
&quot;account_id&quot;: &quot;34D015FCDA78A87A07FA5CF3B5276523&quot;,
&quot;game_appid&quot;: &quot;ks123456789&quot;,
&quot;sign&quot;: &quot;fc75644f87ab7ffa9fc85310f4b9b6c6fb4d84c9&quot;
}</code></pre>
<h2>4.4接口返回</h2>
<pre><code class="language-javascript">Callback: {&quot;code&quot;:1,&quot;msg&quot;:&quot;成功&quot;,&quot;time&quot;:&quot;1721272731&quot;,&quot;data&quot;:null}</code></pre>
<h1>5.激励视频广告看完（有激励视频必须上报）</h1>
<h2>5.1接口说明</h2>
<p><div style="background: #9efca6;padding: 12px; border-radius: 8px; color: #000;">✍激励视频广告看完上报</p>
<p><code>url:</code>
<code>https://cps.moyangmoyang.com/api/ksgame/watch</code>
</div>
<div style="background: #FFE4B5;padding: 12px; border-radius: 8px; color: #000;">⚠️ <strong>注意</strong>
1.只上报激励视频
2.广告close的时候上报
</div></p>
<h2>5.2参数说明</h2>
<p>|参数名|必选|类型|说明|
|:---- |:---|:----- |----- |
|game_appid |是 |string | 游戏appid |
|account_id |是 |string | 玩家openid：小游戏服务器从快手服务器获取 |
|sign |是 |string | 生成签名 |</p>
<h2>5.3示例代码</h2>
<pre><code class="language-javascript">{
&quot;account_id&quot;: &quot;34D015FCDA78A87A07FA5CF3B5276523&quot;,
&quot;game_appid&quot;: &quot;ks123456789&quot;,
&quot;sign&quot;: &quot;fc75644f87ab7ffa9fc85310f4b9b6c6fb4d84c9&quot;
}</code></pre>
<h2>5.4接口返回</h2>
<pre><code class="language-javascript">Callback: {&quot;code&quot;:1,&quot;msg&quot;:&quot;成功&quot;,&quot;time&quot;:&quot;1721272731&quot;,&quot;data&quot;:null}</code></pre>
<h1>6.在线时长上报</h1>
<h2>6.1接口说明</h2>
<p><div style="background: #9efca6;padding: 12px; border-radius: 8px; color: #000;">✍统计在线时长(用户打开到退出的停留时长)</p>
<p><code>url:</code>
<code>https://cps.moyangmoyang.com/api/ksgame/timing</code>
</div>
<div style="background: #FFE4B5;padding: 12px; border-radius: 8px; color: #000;">⚠️ <strong>注意</strong>
1.大于60秒才上报
2.可以分片上传，可以退出后一次性传，同用户后台会自动累加
</div></p>
<h2>6.2参数说明</h2>
<p>|参数名|必选|类型|说明|
|:---- |:---|:----- |----- |
|timing |是 |int | 在线时长（秒）,大于等于60秒才上报，可以分片上传，可以退出后一次性传，同用户后台会自动累加 |
|game_appid |是 |string | 游戏appid |
|account_id |是 |string | 玩家openid：小游戏服务器从快手服务器获取 |
|sign |是 |string | 生成签名 |</p>
<h2>6.3示例代码</h2>
<pre><code class="language-javascript">{
&quot;account_id&quot;: &quot;34D015FCDA78A87A07FA5CF3B5276523&quot;,
&quot;game_appid&quot;: &quot;ks123456789&quot;,
&quot;timing&quot;: &quot;100&quot;,
&quot;sign&quot;: &quot;c95a975b80fb4fa875ecd0b062a50367b124e8d8&quot;
}</code></pre>
<h2>6.4接口返回</h2>
<pre><code class="language-javascript">Callback: {&quot;code&quot;:1,&quot;msg&quot;:&quot;成功&quot;,&quot;time&quot;:&quot;1721272731&quot;,&quot;data&quot;:null}</code></pre>
<h1>7.关卡等级上报</h1>
<h2>7.1接口说明</h2>
<p><div style="background: #9efca6;padding: 12px; border-radius: 8px; color: #000;">✍关卡等级或者分数记录</p>
<p><code>url:</code>
<code>https://cps.moyangmoyang.com/api/ksgame/game_level</code>
</div></p>
<h2>7.2参数说明</h2>
<p>|参数名|必选|类型|说明|
|:---- |:---|:----- |----- |
|level |是 |int | 等级或者积分 |
|game_appid |是 |string | 游戏appid |
|account_id |是 |string | 玩家openid：小游戏服务器从快手服务器获取 |
|sign |是 |string | 生成签名 |</p>
<h2>7.3示例代码</h2>
<pre><code class="language-javascript">{
&quot;game_appid&quot;: &quot;tt3f354988a007dbb002&quot;,
&quot;account_id&quot;: &quot;34D015FCDA78A87A07FA5CF3B5276523&quot;,
&quot;level&quot;: 1,
&quot;sign&quot;: &quot;f207be6284584633b1023c8b2dc1156f&quot;
}</code></pre>
<h2>7.4接口返回</h2>
<pre><code class="language-javascript">Callback: {&quot;code&quot;:1,&quot;msg&quot;:&quot;成功&quot;,&quot;time&quot;:&quot;1721272731&quot;,&quot;data&quot;:null}</code></pre>
<h1>8.广告点上报</h1>
<h2>8.1接口说明</h2>
<p><div style="background: #9efca6;padding: 12px; border-radius: 8px; color: #000;">✍广告点上报，看广告时调用</p>
<p><code>url:</code>
<code>https://cps.moyangmoyang.com/api/ksgame/adnamereward</code>
</div></p>
<h2>8.2参数说明</h2>
<p>|参数名|必选|类型|说明|
|:---- |:---|:----- |----- |
|game_appid |是 |string | 游戏appid |
|account_id |是 |string | 玩家openid，小游戏服务器从快手服务器获取 |
|ad_name |是 |string |广告位名称 |
|ad_is_reward |是 |int |是否获得广告奖励 0否，1是(只要看完广告就传1,没看完传0) |
|sign |是 |string | 生成签名 |</p>
<h2>8.3示例代码</h2>
<pre><code class="language-javascript">//广告未看完
{
&quot;game_appid&quot;: &quot;ks123456789&quot;,
&quot;account_id&quot;: &quot;34D015FCDA78A87A07FA5CF3B5276523&quot;,
&quot;ad_name&quot;: &quot;广告未看完（这是广告点示例，要传当前广告点名称，名称不要带广告未看完）&quot;,
&quot;ad_is_reward&quot;: 0, //0未获得奖励，1获得奖励，必传((点击了广告未看完传0))
&quot;sign&quot;: &quot;f207be6284584633b1023c8b2dc1156f&quot;
}
//广告看完
{
&quot;game_appid&quot;: &quot;ks123456789&quot;,
&quot;account_id&quot;: &quot;34D015FCDA78A87A07FA5CF3B5276523&quot;,
&quot;ad_name&quot;: &quot;广告看完（这是广告点示例，要传当前广告点名称，名称不要带广告看完）&quot;,
&quot;ad_is_reward&quot;: 1, //0未获得奖励，1获得奖励，必传((只要看完广告就传1))
&quot;sign&quot;: &quot;f207be6284584633b1023c8b2dc1156f&quot;
}</code></pre>
<h2>8.4接口返回</h2>
<pre><code class="language-javascript">上报广告名称:{&quot;code&quot;:1,&quot;msg&quot;:&quot;成功&quot;,&quot;time&quot;:&quot;1717141847&quot;,&quot;data&quot;:null}</code></pre>