Kango JSSDK 开发文档

概述

Kango JSSDK 是一套让 H5 网页调用 Kango App 原生能力的桥接库。通过在 h5App（H5 页面）中引入 kg.js，开发者可以：

获取当前用户在某个 h5App 的 openId 和公开资料
获取当前用户的全局唯一 unionId
调用相机、相册、扫码等原生功能
唤起支付界面
接收来自 App 的主动消息推送

INFO

h5App 运行在 Kango App 内的 WebView 中，App 会在 WebView 加载完成前注入 window.__KANGO_USER_TOKEN 和 window.__KANGO_BASE_URL。

快速接入

第一步：引入 JS

在 H5 页面的 <head> 中引入：

html

<script src="/jssdk/jssdk.js"></script>

或直接使用 CDN（同域 App 服务地址）：

html

<script src="http://your-server.com/jssdk/jssdk.js"></script>

第二步：初始化

kg.init({ appKey: 'YOUR_APP_KEY' });

第三步：调用 API

kg.ready(function () {
  var openId = kg.getOpenId();
  console.log('openId:', openId);
});

网站域名验证

当 miniApp 配置了「网站域名」后，服务端会在每次 kg.init 时校验该域名的所有权，未通过则拒绝初始化。验证方式：在网站根目录放置一个以 WebsiteKey 命名、内容也为 WebsiteKey 的文本文件。

在开发者中心「小程序列表」配置「网站域名」（如 https://www.example.com）并保存，系统自动生成 WebsiteKey。
点击「下载验证文件」，得到 kg_verify_{WebsiteKey}.txt（文件内容为该 WebsiteKey）。
将文件上传到网站根目录，确保可通过 https://你的域名/kg_verify_{WebsiteKey}.txt 直接访问。
完成后再次调用 kg.init 即可通过域名验证。

支持两种验证文件名（内容均为 WebsiteKey），服务端优先尝试第 1 种，访问不到再尝试第 2 种：

kg_verify_{WebsiteKey}.txt（主要，固定前缀命名，便于在根目录识别管理）
{WebsiteKey}.txt（次要，兼容旧版）

验证文件示例（文件名 kg_verify_3f9a8c…c21e.txt 或 3f9a8c…c21e.txt，内容如下）：

text

文件名: kg_verify_3f9a8c1b...c21e.txt   （或旧版 3f9a8c1b...c21e.txt）
内容:   3f9a8c1b...c21e

（两种文件名任选其一，文件内容均为该应用的 WebsiteKey）

服务端校验：依次请求 {website}/kg_verify_{WebsiteKey}.txt 和 {website}/{WebsiteKey}.txt，去除首尾空白后与 WebsiteKey 比对，任一相同即视为拥有该域名。

初始化

kg.init(cfg)

初始化 JSSDK，必须在调用其他 API 之前调用。

参数	类型	必填	说明
`cfg.appKey`	string	是	在开发者中心创建应用后获得的 AppKey

kg.ready(callback)

JSSDK 初始化完成后触发，确保在此回调内调用其他 API。

kg.ready(function () {
  // JSSDK 已初始化，可以调用任意 API
});

用户相关

kg.getOpenId()

获取当前用户在本 h5App 内的唯一标识（openId）。同一用户在不同 h5App 中 openId 不同。

var openId = kg.getOpenId(); // string

kg.getUnionId()

获取当前用户的全局唯一 unionId。

var unionId = kg.getUnionId(); // string

kg.getUserProfile(callback)

获取用户公开资料，需用户已授权（SDK init 完成即代表授权）。

返回字段：

字段	类型	说明
`openId`	string	用户在本 h5App 的唯一 ID
`nickname`	string	用户昵称
`avatar`	string	头像 URL
`sex`	number	性别：0-未知 1-男 2-女
`guid`	string	用户全局唯一 ID
`faceUrl`	string	IM 头像 URL

kg.getUserProfile(function (err, profile) {
  if (err) { console.error(err); return; }
  console.log(profile.openId);
  console.log(profile.nickname);
  console.log(profile.avatar);
});

原生能力

chooseImage — 选择图片

从相册选择图片。回调参数：{ uri: string, base64: string }

kg.chooseImage(function (err, res) {
  if (err) return;
  // res.uri   — 本地文件路径
  // res.base64 — base64 字符串
  console.log(res.uri);
});

takePhoto — 拍照

调起相机拍照。回调参数：{ uri: string, base64: string }

kg.takePhoto(function (err, res) {
  if (err) return;
  console.log(res.uri, res.base64);
});

scanQR — 扫码

扫描二维码或条形码。回调参数：{ data: string }

kg.scanQR(function (err, res) {
  if (err) return;
  console.log('扫码结果:', res.data);
});

playVideo — 播放视频

调起 App 内视频播放器。参数：{ url: string, title?: string }

kg.playVideo({ url: 'https://example.com/video.mp4', title: '视频标题' });

closeWindow — 关闭窗口

关闭当前 WebView 窗口。

kg.closeWindow();

alert — 原生弹窗

调起原生 Alert 弹窗。参数：{ title?: string, message: string }

kg.alert({ title: '提示', message: '操作成功！' });

onMessage — 接收推送

监听 App 主动下发的命令消息。

kg.onMessage(function (msg) {
  if (msg.type === 'command') {
    console.log('收到 App 消息:', msg);
  }
});

支付

kg.pay(opts, callback)

参数	类型	说明
`type`	`'wechat'` \| `'alipay'`	支付方式
`amount`	number	金额（分）
`orderId`	string	商户订单号
`subject`	string	商品描述

kg.pay({
  type: 'wechat',
  amount: 100,        // 1 元
  orderId: 'ORDER_001',
  subject: '商品购买'
}, function (err, result) {
  if (err) { console.error('支付失败:', err); return; }
  console.log('支付成功:', result);
});

服务端 API

以下接口供 h5App 后端服务调用，需要 access_token（通过 AppKey + AppSecret 获取）。

获取 access_token

http

POST /api/mini/token
Content-Type: application/json

{
  "appKey": "YOUR_APP_KEY",
  "appSecret": "YOUR_APP_SECRET"
}

响应：

json

{
  "code": 200,
  "data": {
    "access_token": "xxxxxxxx",
    "expires_in": 7200
  }
}

获取用户资料

通过服务端调用，根据 jsapi_ticket 换取用户信息。

http

GET /api/mini/user/profile
X-Kango-Ticket: {jsapi_ticket}

响应：

json

{
  "code": 200,
  "data": {
    "openId": "xxxx",
    "nickname": "张三",
    "avatar": "https://...",
    "sex": 1,
    "guid": "xxxx"
  }
}

安全提示

AppSecret 务必保存在服务端，不要暴露在前端代码中。

Kango JSSDK 开发文档 ​

概述 ​

快速接入 ​

第一步：引入 JS ​

第二步：初始化 ​

第三步：调用 API ​

网站域名验证 ​

初始化 ​

kg.init(cfg) ​

kg.ready(callback) ​

用户相关 ​

kg.getOpenId() ​

kg.getUnionId() ​

kg.getUserProfile(callback) ​

原生能力 ​

chooseImage — 选择图片 ​

takePhoto — 拍照 ​

scanQR — 扫码 ​

playVideo — 播放视频 ​

closeWindow — 关闭窗口 ​

alert — 原生弹窗 ​

onMessage — 接收推送 ​

支付 ​

kg.pay(opts, callback) ​

服务端 API ​

获取 access_token ​

获取用户资料 ​