jf-gamekit

v1.1.0

Published

a month ago

> 目前只支持「微信」、「抖音」小游戏，其中 jf_active、jf_login、jf_pay、jf_trace 这四个方法必须接入。 > > 接入方在接入前需要在开放平台配置 request 合法域名：https://page.hurricanegame.cn

0High
0Medium
0Low

hurricanegame

小游戏 SDK 使用说明

目前只支持「微信」、「抖音」小游戏，其中 jf_active、jf_login、jf_pay、jf_trace 这四个方法必须接入。
接入方在接入前需要在开放平台配置 request 合法域名：https://page.hurricanegame.cn

SDK 接入

SDK 目前提供两种接入方式：

直接引入
通过 npm 安装

⚠️ TypeScript 项目请使用 npm 的方式引入 SDK !!! 如果项目不支持 npm，请自行拿 index.d.ts 去做调整。npm 地址：https://www.npmjs.com/package/jf-gamekit

直接引入

jf-gamekit 提供三种类型文件，分别是：

ESModule：位于 es 目录下，包含抖音 sdk（ttSdk.es.js）和微信 sdk （wxSdk.es.js）；
CommonJS：位于 lib 目录下，包含抖音 sdk（ttSdk.js）和微信 sdk（wxSdk.js）;
UMD：位于 umd 目录下，包含抖音 sdk（ttSdk.umd.js）和微信 sdk（wxSdk.umd.js），unity 可用。

开发者可根据自己项目的情况，对 sdk 文件按需放置到自己的项目中进行使用。

通过 npm 安装

使用步骤：(以微信小游戏为例)

初始化 package.json（如果有，则忽略），命令：npm init
npm 安装 @jf/jf-gamekit，安装命令：npm i jf-gamekit
在开发者工具中点击 "工具 -> 构建 npm"

API

以下示例均以 npm 为例，如果不支持 npm 的项目请按需从 es、umd 或 lib 取对应的文件引入。如果项目需要 ts，请使用 index.d.ts 根据自己的项目情况自行做调整。

【通】激活 jf_active

提供小游戏激活能力。

此方法支持 Promise 风格调用，推荐使用 async/await 或 .then() 处理异步结果。
前提条件：-
使用限制：-
注意事项：需尽早初始化 SDK，避免数据丢失；微信小游戏如需要接入广点通，只需提供广点通相关配置。提供后，接入方无需处理，SDK 会在 jf_active 方法内自行接入。

语法示例

import { jf_active } from 'jf-gamekit'

jf_active(options).then((res) => {
  // 成功了...
}).catch((err) => {
  // 失败了...
});

参数说明

options 为 object 类型，属性如下：

| 属性名 | 说明 | 类型 | 必填 | 版本 | |--------|------|------|------|------| | wx | 微信小游戏基础配置 | object | 微信时必填 | 1.0.0 | | tt | 抖音小游戏基础配置 | object | 抖音时必填 | 1.0.0 |

wx 或 tt 属性说明：

wx 或 tt 均为 object 类型，属性如下：

| 属性名 | 说明 | 类型 | 必填 | 版本 | |--------|------|------|------|------| | game_id | 游戏ID | string | 是 | 1.0.0 | | version | 小游戏版本号 | string | 是 | 1.0.0 | | app_id | 小游戏 appId | string | 是 | 1.0.0 | | dn_sdk_id | 广点通数据源ID，接入广点通需提供（仅支持微信小游戏） | number | 否 | 1.0.0 | | dn_secret_key | 广点通加密秘钥，接入广点通需提供（仅支持微信小游戏） | string | 否 | 1.0.0 |

options 示例：

const config = {
  // 微信小游戏基础配置
  wx: {
    app_id: '',
    dn_secret_key: '',
    version: '1.0.0'
    // ...
  },

  // 抖音小游戏基础配置
  tt: {
    app_id: '',
    // ...
  }
}

回调成功

回调成功未返回信息，直接在 .then 成功回调中处理自己逻辑即可。

回调失败

object 类型，属性如下：

| 属性名 | 说明 | 类型 | 版本 | | ---- | ---- | ---- | ---- | | state | 状态：100001-激活入参缺失100002-激活入参 wx 属性缺失100003-激活入参 game_id 属性缺失 | number | 1.0.0 | | msg | 提示信息 | string | 1.0.0 |

【通】登录 jf_login

提供小游戏登录能力。

此方法支持 Promise 风格调用，推荐使用 async/await 或 .then() 处理异步结果。
前提条件：调用 js_active 激活成功后，方可调用此方法进行登录。
使用限制：-
注意事项：用户登录之后会返回登录信息，cp 方需要用 token 请求我方服务端接口获得用户账号 uid。

语法示例

import { jf_login } from 'jf-gamekit'

jf_login().then((res) => {
  // 成功了...
}).catch((err) => {f
  // 失败了...
});

参数说明

此方法无需入参。

回调成功

object 类型，属性如下：

| 属性 | 说明 | 类型 | 版本 | | ---- | ---- | ---- | ---- | | token | 用户 token | string | 1.0.0 | | uid | 用户 uid | string | 1.0.0 | | uname | 用户名 | string | 1.0.0 | | partner_id | 联运商ID | number | 1.0.0 | | show_page | / | number | 1.0.0 |

回调失败

object 类型，属性如下：

| 属性名 | 说明 | 类型 | 版本 | | ---- | ---- | ---- | ---- | | state | 状态：100001: 接口请求出错100002: wx.login 或 tt.login 出错100003: 登录前未激活其他状态解释省略，开发需要时可沟通 | number | 1.0.0 | | msg | 提示信息 | string | 1.0.0 |

【通】支付 jf_pay

提供小游戏支付能力。安卓平台调用米大师支付，ios平台进入客服会话充值。

此方法支持 Promise 风格调用，推荐使用 async/await 或 .then() 处理异步结果。
前提条件：调用过激活 jf_active 和登录 jf_login之后方可调用此方法。
使用限制：-
注意事项：-

语法示例

import { jf_pay } from 'jf-gamekit'

jf_pay(options).then((res) => {
  // 成功了...
}).catch((err) => {
  // 失败了...
});

参数说明

object 类型，属性如下

| 属性名 | 说明 | 类型 | 必填 | 版本 | | ------- | --------------------- | ------ | ---- | ----- | | doid | CP订单ID | string | 是 | 1.0.0 | | dsid | CP游戏服ID(标识) | string | 是 | 1.0.0 | | dsname | 服务器名字 | string | 否 | 1.0.0 | | dext | CP扩展回调参数,225字符 | string | 否 | 1.0.0 | | drid | CP角色ID | string | 否 | 1.0.0 | | drname | CP角色名 | string | 否 | 1.0.0 | | dlevel | CP角色等级 | number | 否 | 1.0.0 | | dmoney | CP金额(定额) | number | 是 | 1.0.0 |

回调成功

回调成功未返回信息，直接在 .then 成功回调中处理自己逻辑即可。

回调失败

object 类型，属性如下：

| 属性名 | 说明 | 类型 | 版本 | |--------|------|------|------| | state | 状态：• 100001 - 未激活或未登录，无法完成支付• 100002 - 下单内部出错，无法完成支付• 100004 - 设备信息(ios/Android)未识别，无法完成支付• 其他状态码省略（开发需要时联系） | number | 1.0.0 | | msg | 提示信息 | string | 1.0.0 |

【通】数据上报 jf_trace

提供小游戏在进入游戏、创建角色、角色升级时数据上报能力。

此方法支持 Promise 风格调用，推荐使用 async/await 或 .then() 处理异步结果。
前提条件：调用过激活 jf_active 和登录 js_login之后方可调用此方法。
使用限制：-
注意事项：-

语法示例：

import { jf_trace } from 'jf-gamekit'

jf_trace(options).then(res => {
  // 成功
}).catch(err => {
  // 失败
})

参数说明

object 类型，属性如下：

| 属性名 | 说明 | 类型 | 必填 | 版本 | |----------|----------------------|--------|------|-------| | dsid | CP游戏服ID(标识) | string | 是 | 1.0.0 | | dsname | 服务器名字 | string | 否 | 1.0.0 | | drid | CP角色ID | string | 否 | 1.0.0 | | drname | CP角色名 | string | 否 | 1.0.0 | | drlevel | CP角色等级 | number | 否 | 1.0.0 | | event | 事件类型create: 创建角色enter: 进入游戏levelup: 角色升级 | string | 是 | 1.0.0 |

回调成功

回调成功未返回信息，直接在 .then 成功回调中处理自己逻辑即可。

回调失败

object 类型，属性如下：

| 属性名 | 说明 | 类型 | 版本 | |--------|------|------|------| | state | 状态：• 100001 - 未激活或未登录• 100002 - 接口请求出错• 其他状态码省略（开发需要时联系） | number | 1.0.0 | | msg | 提示信息 | string | 1.0.0 |

【通】客服 jf_customerService

提供小游戏唤起客服能力。

此方法支持不 Promise 风格调用。
前提条件：-
使用限制：抖音小游戏 c# 不支持
注意事项：调用此方法前，如果未调用过激活 jf_active 和登录 js_login，则数据上报会失败。

语法示例

import { jf_customerService } from 'jf-gamekit'

jf_customerService(options)

参数说明

object 类型，属性如下：

回调成功

无成功回调。

回调失败

无失败回调。

【通】激励视频 jf_createRewardedVideoAd

提供小游戏展示激励视频的能力。此方法内部包含两个方法，分别是预加载和展示视频。其中预加载功能可根据项目情况选择使用。

此方法支持 Promise 风格调用，推荐使用 async/await 或 .then() 处理异步结果。
前提条件：-
使用限制：-
注意事项：preload 提供预加载能力，请在合适位置调用，不可和 show 调用出现在一个方法里！！！此方法内使用到了 onClose 来监听用户是否看完广告，抖音的 onClose 内部对广告实例做了「销毁」处理，请合理使用「激励视频」方法，避免频繁调用，有疑问可随时联系。

语法示例

import { jf_createRewardedVideoAd } from 'jf-gamekit'

const rewardedAd = jf_createRewardedVideoAd('adunit-321232132');


// 可提前预加载广告（可选择性调用）
rewardedAd.preload()
  .then(() => console.log('广告预加载完成'))
  .catch(err => console.error('预加载失败:', err))


// 展示激励视频
rewardedAd.show()
  .then((res) => console.log('视频已展示'))
  .catch(err => console.log('视频展示失败'))
}

参数说明

string 类型，属性如下：

| 属性名 | 说明 | 类型 | 必填 | 版本 | |----------|----------------------|--------|------|-------| | adUnitId | 广告单元ID | string | 是 | 1.0.0 |

回调成功

object 类型，属性如下：

| 属性名 | 说明 | 类型 | 版本 | |----------|----------------------|--------|-------| | isEnded | 用户是否看完广告：true - 看完；false - 中途关闭 | boolean | 1.0.0 |

回调失败

object 类型，属性如下：

| 属性名 | 说明 | 类型 | 版本 | |----------|----------------------|--------|-------| | state | 状态：100001 - 预加载失败，无法展示广告；100002 - 广告实例不存在；100003 - 视频展示失败 | number | 1.0.0 | | msg | 提示信息 | string | 1.0.0 |

【通】获取用户信息 jf_getUserInfo

提供小游戏获取用户信息能力。

此方法支持 Promise 风格调用，推荐使用 async/await 或 .then() 处理异步结果。
前提条件：-
使用限制：-
注意事项：用户未授权的情况下，微信小游戏不会默认弹出授权窗口，而是需要用户主动触发（如点击按钮），直接调用会违反微信的隐私政策。

语法示例

import { jf_getUserInfo } from 'jf-gamekit'

jf_getUserInfo().then((res) => {
  // 成功了...
}).catch((err) => {
  // 失败了...
});

参数说明

此方法无需入参

回调成功

object 类型，属性如下：

| 属性名 | 说明 | 类型 | 版本 | |----------|----------------------|--------|-------| | avatarUrl | 用户头像 | string | 1.0.0 | | country | 用户所在国家 | string | 1.0.0 | | province | 用户所在省份 | string | 1.0.0 | | city | 用户所在城市 | string | 1.0.0 | | gender | 用户性别 | number | 1.0.0 | | language | 用户所用的语言 | string | 1.0.0 | | nickName | 用户昵称 | string | 1.0.0 |

回调失败

object 类型，属性如下：

| 属性名 | 说明 | 类型 | 版本 | |----------|----------------------|--------|-------| | state | 状态：100001-获取信息失败 | number | 1.0.0 | | msg | 提示信息 | string | 1.0.0 |

【通】敏感词检验 jf_profanityCheck

提供小游戏在用户创角、发布言等交互场景时的敏感词过滤能力。

此方法支持 Promise 风格调用，推荐使用 async/await 或 .then() 处理异步结果。
前提条件：-
使用限制：-
注意事项：
微信：敏感词校验请结合CP自身敏感词库使用，两边都校验合规则通过内容，否则违规！
抖音：内部使用了 tt.onKeyboardComplete，请结合自身业务，避免重复调用onKeyboardComplete。如果未检测到用户有输入值，则会走到失败回调。

语法示例

import { jf_profanityCheck } from 'jf-gamekit'

jf_profanityCheck(options).then(res => {
  // 成功
}).catch(err => {
  // 失败
})

参数说明

object 类型，属性如下：

| 属性名 | 说明 | 类型 | 必填 | 版本 | |----------|----------------------|--------|------|-------| | game_id | 游戏ID | string | 是 | 1.0.0 | | version | 游戏版本号 | string | 是 | 1.0.0 | | content | 校验内容 | string | 是 | 1.0.0 | | scene | 校验文本类型枚举值：1：账号信息2：评论3：论坛4：社交互动 | string | 是 | 1.0.0 |

回调成功

微信：回调成功未返回信息，直接在 .then 成功回调中处理自己逻辑即可。
抖音：回调成功时返回用户输入的值，如有敏感字符则会用**代替。

回调失败

| 属性名 | 说明 | 类型 | 版本 | |----------|----------------------|--------|-------| | state | 状态：100001-敏感词未通过检验（抖音是未检测到有输入） 100002-接口请求出错（仅微信）其他状态解释省略，开发需要时可沟通| number | 1.0.0 | | msg | 提示信息 | string | 1.0.0 |

【wx】分享 jf_share

提供小游戏唤起分享能力。

此方法支持不 Promise 风格调用。
前提条件：-
使用限制：仅支持微信小游戏。
注意事项：调用此方法前，如果未调用过激活 jf_active 和登录 js_login，则数据上报会失败。

语法示例

import { jf_share } from 'jf-gamekit'

jf_share(options)

参数说明

object 类型，属性如下：

回调成功

无成功回调。

回调失败

无失败回调。

【wx】浏览页面上报数据 jf_tracePageView

提供小游戏浏览页面时上报数据的能力。

此方法支持 Promise 风格调用，推荐使用 async/await 或 .then() 处理异步结果。
前提条件： -
使用限制：仅支持微信小游戏
注意事项：-

语法示例

import { jf_tracePageView } from 'jf-gamekit'

jf_tracePageView(options).then((res) => {
  // 成功了...
}).catch((err) => {
  // 失败了...
});

参数说明

string类型，属性如下：

| 属性名 | 说明 | 类型 | 必填 | 版本 | |----------|----------------------|--------|------|-------| | content | 浏览的页面：Mall - 浏览商城页Activity - 浏览活动页 | string | 是 | 1.0.0 |

回调成功

回调成功未返回信息，直接在 .then 成功回调中处理自己逻辑即可。

回调失败

object 类型，属性如下：

| 属性名 | 说明 | 类型 | 版本 | |----------|----------------------|--------|-------| | state | 状态：100001-广点通 SDK 未初始化| number | 1.0.0 | | msg | 提示信息 | string | 1.0.0 |

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

小游戏 SDK 使用说明

SDK 接入

直接引入

通过 npm 安装

API

【通】激活 jf_active

语法示例

参数说明

wx 或 tt 属性说明：

回调成功

回调失败

【通】登录 jf_login

语法示例

参数说明

回调成功

回调失败

【通】支付 jf_pay

语法示例

参数说明

回调成功

回调失败

【通】数据上报 jf_trace

语法示例：

参数说明

回调成功

回调失败

【通】客服 jf_customerService

语法示例

参数说明

回调成功

回调失败

【通】激励视频 jf_createRewardedVideoAd

语法示例

参数说明

回调成功

回调失败

【通】获取用户信息 jf_getUserInfo

语法示例

参数说明

回调成功

回调失败

【通】敏感词检验 jf_profanityCheck

语法示例

参数说明

回调成功

回调失败

【wx】分享 jf_share

语法示例

参数说明

回调成功

回调失败

【wx】浏览页面上报数据 jf_tracePageView

语法示例

参数说明

回调成功

回调失败