看购网页开发 · 起步指南

看购H5APP ，就是普通网页运行在看购 App 内置浏览器中时，可以额外调用一些看购能力：识别用户身份、调起相机与扫码、唤起支付、接收消息推送等, 与微信公众号的开发和功能相似。

这些能力通过 看购 JSSDK 提供,并保持与微信公众号JSSDk的方法名和参数保持接口一致。你原有的面向微信公众号的 H5站点不需要重写，引入一个看购jssdk文件、加几行初始化代码，就能在看购 App 中使用,实现替换原来的微信公众号的功能代码 .

入门之前，需要你具备基本的网页开发基础。如果你完全没有接触过网页开发，建议先了解 HTML、CSS 和 JavaScript和微信公众号的开发基础。

一、起步前准备

开始之前，先确认这几件事：

你需要	说明
一个看购 App 账号	开放平台的登录账号就是 App 账号，不需要另行注册
认证开通圈子服务商账号	需要联系看购平台客服办理
一个可公网访问的网站	你的 H5 页面要放在自己的服务器上，看购不托管你的代码
该网站的根目录写入权限	域名验证需要往根目录放一个文本文件
一台装了看购 App 的手机	真机调试是唯一能验证原生能力的方式

开通链路

五步，顺序是强制的，每一步都是下一步的前置条件：

① 实名认证（看购 App 内）
      ↓
② 主体认证 · 圈子服务商（联系平台客服办理，账号级）
      ↓
③ 登录开放平台，创建 H5APP，拿到 AppKey / AppSecret
      ↓
④ 应用认证（每个 H5APP 单独一次）→ 审核通过后应用上线
      ↓
⑤ 域名验证 → 配置 H5 入口 → 写页面

开放平台只对已认证的圈子服务商及其绑定的运营者开放：第 ② 步完成之前登录会提示「没有权限」。第 ④ 步通过之前，应用处于「待认证」，不能上线。

名词解释

名词	含义
H5APP	你在看购开放平台创建的应用。一个 H5APP 对应一套 `AppKey` / `AppSecret` 和一个 H5 入口地址
AppKey	应用的公开标识，可以出现在前端代码里
AppSecret	应用密钥，只能保存在你的服务器上
openId	用户在你这个 H5APP 内的唯一标识。同一个用户在不同 H5APP 中的 openId 不同
unionId	同一开发者主体名下多个 H5APP 共享的用户标识，用于识别"这几个应用里是同一个人"
WebsiteKey	域名归属校验用的字符串，创建应用填写网站域名后自动生成
关注用户	用户在你的 H5APP 里完成一次初始化后，即成为该应用的关注用户，可在开发者中心看到

二、注册与实名认证

2.1 下载看购 App 并注册

在应用商店搜索"看购"，或官网(https://kg.citv.cc)扫描二维码下载。安装后用手机号注册账号。目前已上线的安卓平台包括:应用宝、小米、华为,荣耀,oppo,vivo等,ios平台正在审核中。

2.2 完成实名认证

实名认证是开通开放平台能力的第一步，且只能在看购 App 内完成，开放平台网站不提供这个入口。

打开看购 App，进入「我的 → 实名认证」，按提示提交身份信息。

App 内实名认证入口

WARNING

没有完成实名认证，不能创建应用、不能提交应用认证。审核通常在 1 个工作日内完成。

三、主体认证

这一步是使用开放平台的前置条件

只有「圈子服务商」主体认证有效的账号（及其绑定的运营者）才能登录开放平台、创建 H5APP。 其余主体类型（普通企业、政府机关、媒体事业、个人）可以认证，但不能使用开发者中心。

3.1 主体认证挂在你的账号上

看购的主体认证是账号级的，决定你能不能使用开发者中心、创建 H5APP。

注意它不代替应用认证：创建出来的每个 H5APP 还要单独提交一次应用认证，通过后才能上线，应用认证提交的企业资料跟主体企业的可以不同, 见应用认证。

3.2 办理认证

主体认证由平台客服办理：联系看购平台客服，提供下列材料和你的看购账号（注册手机号或用户名），客服核实后在后台为该账号完成认证。开放平台网站上不提供主体认证的提交入口，登录后可以在「应用管理 → 主体认证」查看认证详情。

资质认证

主体类型决定了你能做什么：

主体类型	能创建 H5APP	说明
圈子服务商	✅	对外提供软件服务的企业。要建应用选这个
普通企业	❌	仅展示「已认证」标识
政府机关	❌	同上
媒体事业	❌	同上
个人认证	❌	同上

各类型需要的材料：

主体类型	需要的材料
圈子服务商 / 普通企业	营业执照编号 + 营业执照图片、法定代表人姓名 + 身份证正反面、企业地址、联系邮箱与电话
政府机关 / 媒体事业	单位名称、地址、负责人姓名 + 身份证正反面、联系邮箱与电话
个人认证	真实姓名 + 身份证正反面、联系邮箱与电话

一张营业执照只能绑一个账号

同一个营业执照号在看购只能被一个开发者账号使用。换账号提交同一张执照会被拒绝，需要转移请联系平台客服。同一账号的主体认证和各应用认证填同一张执照没有问题。

认证有效期 3 年。过期后该账号及其运营者不能登录开发者中心，请在到期前联系客服续期；已上线的应用是否在线看各自的应用认证，不受主体认证过期影响。

四、登录开放平台

主体认证完成后，用同一个看购账号登录看购开放平台：

https://kg.citv.cc/kango

开放平台登录页

账号既不是已认证的圈子服务商、也没有被绑定为运营者：登录时提示「没有权限」。
账号能代表多个认证主体（自己是圈子服务商，同时又是别人的运营者）：登录后弹出主体列表，选一个进入。之后可以在顶栏随时「切换」。

登录后进入开发者中心首页：

开发者中心首页

4.1 运营者

主账号（圈子服务商本人）可以在「应用设置 → 人员管理」中绑定运营者，让团队成员用自己的看购账号 ,代为管理h5App：

按对方的手机号或用户名查到人，核对昵称头像后绑定；授权可以选「长期」或设置截止时间
每个主账号最多同时绑定 25 个运营者；解绑后对方立即失去权限
运营者登录时选择代表你的主体，可以管理你名下的全部 H5APP（创建应用、应用认证、支付渠道、机器人等）
运营者不能查看或变更主体认证，不能管理运营者

4.2 切换身份和选择 h5App

用户登录后，可以在顶栏随时「切换」代表的主体，也可以在「应用管理 → 应用列表」里选择要操作的 H5APP。切换身份和选择 h5App

五、创建你的第一个 H5APP

前置条件

需要已实名认证（实名看的是当前登录操作的账号，运营者代建时看运营者本人）且当前主体**「圈子服务商」主体认证有效**。见主体认证。

进入「应用管理 → 应用列表」，点击「创建应用」。

创建应用

需要填写的字段：

字段	必填	说明
应用名称	✅	会展示给用户，建议用产品名
网站域名	✅	你的 H5 页面所在域名，如 `https://www.example.com`。保存后自动生成 `WebsiteKey`
应用图标		建议正方形，jpg/png/webp，不超过 2M
H5 路径		用户点击你的应用时打开的地址。留空则使用网站域名
描述		应用简介

创建成功后，在应用列表可以看到这个应用的 AppKey 和 AppSecret。新应用的状态是「待认证」。

应用凭证

应用认证

应用认证通过前，应用不能上线

每个 H5APP 都要单独提交应用认证，不沿用账号的主体认证。「待认证」状态下：

应用列表里的上线开关不可用；
JSSDK 初始化、服务端 access_token、OAuth 授权登录、机器人接口与消息回调、小程序卡片 全部不可用。

在应用列表点应用状态旁的「去认证」，或进入「应用设置 → 账号设置 → 应用认证」
填写这个应用实际运营主体的资质（材料要求同主体认证，主体类型不限，需重新填写）
审核通过后应用自动上线；如果你在审核期间手动停用了应用，通过后保持停用，需要自己打开
应用认证被平台退回、改判拒绝或到期（有效期 3 年）时，应用会自动下线回到「待认证」，重新提交通过后恢复

用户在看购 App 里查看应用资料时，展示的「已认证 / 主体名称 / 客服电话」来自这个应用的应用认证。

完成域名验证

看购需要确认你确实拥有填写的那个域名，否则任何人都能拿别人的域名注册应用。

在应用列表点击「下载验证文件」，得到 kg_verify_{WebsiteKey}.txt
把这个文件上传到你网站的根目录
确认能通过 https://你的域名/kg_verify_{WebsiteKey}.txt 直接访问，且内容就是那串 WebsiteKey

下载域名验证文件

常见失败原因

文件放到了子目录（必须是根目录）
服务器把 .txt 当作下载处理，或加了 301 跳转
文件里多了 BOM 头、换行以外的空白字符
网站有 CDN 缓存，文件已上传但边缘节点还是旧的

验证不通过时，kg.config 会直接失败并返回具体原因，不会静默。

六、配置 H5 入口

用户在看购 App 里点开你的应用时，打开的就是「H5 路径」这个地址。

配置 H5 入口

把「H5 路径」填成你自己的页面地址，例如 https://www.example.com/shop/index.html。这个地址必须在前面填写的网站域名之下。

七、写第一个页面

现在可以写代码了。下面是一个完整的最小示例，把它放到你的网站上，通过看购 App 打开就能看到效果。

html

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>我的第一个 H5APP</title>
    <script src="https://kg.citv.cc/jssdk/jssdk.js"></script>
  </head>
  <body>
    <h1>Hello Kango</h1>
    <p id="who">正在识别身份…</p>
    <button id="scan">扫一扫</button>

    <script>
      // 1. 初始化。appId 填你的 AppKey
      kg.config({
        debug: true,
        appId: "YOUR_APP_KEY",
      });

      // 2. 初始化成功后再调用任何接口
      kg.ready(function () {
        document.getElementById("who").innerText =
          "你的 openId：" + kg.getOpenId();
      });

      // 3. 初始化失败走这里（与 ready 互斥，只会触发其中一个）
      kg.error(function (res) {
        document.getElementById("who").innerText = "初始化失败：" + res.errMsg;
      });

      // 4. 调用一个原生能力试试
      document.getElementById("scan").onclick = function () {
        kg.scanQRCode({
          success: function (res) {
            alert("扫到：" + res.resultStr);
          },
          fail: function (res) {
            alert(res.errMsg);
          },
        });
      };
    </script>
  </body>
</html>

三个关键点：

appId 填的是 AppKey，不是 AppSecret。这个字段沿用微信 JSSDK 的命名。
所有接口都要写在 kg.ready 里面。在 ready 之前调用，身份还没就位。
ready 和 error 只会触发其中一个，与微信一致：成功走 ready，失败走 error。所以进了 ready 就代表可以用，失败的处理都写在 error 里。

在普通浏览器里调试

在电脑浏览器直接打开这个页面时，SDK 检测不到 App 注入的身份，会自动进入 mock 模式：openId 是假的，原生能力返回模拟数据。这样你可以先在电脑上把页面逻辑调通，再上真机验证原生能力。

打开 debug: true 后，每次调用的结果都会打到 console。

八、在看购 App 里打开它

页面写好了，用户怎么进来？有两条路径：

会话卡片

把你的 H5APP 分享到聊天会话里，会渲染成一张卡片，点击即打开。

直接打开链接

聊天里发送的链接，如果域名属于某个已登记的 H5APP，看购 App 会自动识别并以该应用的身份打开（带上身份注入）；否则按普通网页打开（不注入身份）。

App 内打开效果

九、接下来做什么

基础流程走完了。按你要做的事情选择下一份文档：

你想做	看这里
调用相机、相册、扫码、获取用户资料	JSSDK 开发文档
在页面里唤起支付	支付接入文档
做一个会自动回消息的机器人	机器人（Bot）开发文档
让用户用看购账号登录你自己的网站	OAuth 2.0 授权登录
把外部平台的直播/点播导入进来	直播/点播导入 API

附录：常见问题

Q：一个账号能创建几个应用？

默认不限制数量。同一开发者名下的多个应用共享 unionId，可以识别出是同一个用户，也共用同一条主体认证；但每个应用要各自通过应用认证才能上线。

Q：登录开放平台提示「没有权限」？

开放平台只对「圈子服务商」主体认证有效的账号及其绑定的运营者开放。请联系平台客服办理主体认证；如果你是团队成员，请让主账号在「人员管理」中把你绑定为运营者。

Q：为什么「创建 H5APP」按钮是灰的？

一般是当前登录的账号还没完成实名认证（在看购 App 内完成）。把鼠标停在按钮上会显示具体原因，开发者中心首页也会提示。

Q：我是普通企业，能不能建 H5APP？

不能。H5APP 是对外提供给第三方用户使用的软件服务，建它的人要为里面运行的代码、收取的资金、留存的用户数据负责，因此要求圈子服务商资质。

如果你的公司确实在对外提供软件服务，联系平台客服把主体类型变更为「圈子服务商」即可，材料是同一套。

Q：每个 H5APP 都要单独认证一次吗？

要。认证分两层：主体认证挂在账号上，决定能不能使用开发者中心、建应用；应用认证每个 H5APP 各做一次，决定这个应用能不能上线。应用认证审核通过前，应用停在「待认证」，JSSDK、授权登录、机器人等能力都不可用。见应用认证。

Q：认证过期了，已经上线的应用会怎样？

看是哪一层过期：

主体认证过期：已上线的应用不受影响，继续运行；但该账号及其运营者不能登录开发者中心，续期请联系客服。
应用认证过期：这个应用自动下线回到「待认证」，重新提交并审核通过后恢复。

Q：同一张营业执照能注册两个开发者账号吗？

不能。一张营业执照只能绑定一个账号，第二个账号提交时会被拒绝。需要转移主体请联系平台客服。

Q：kg.config 一直报域名验证失败怎么办？

先在浏览器里直接访问 https://你的域名/kg_verify_{WebsiteKey}.txt，确认能打开、内容正确、没有跳转。这一步能通过，config 就能通过。

Q：为什么 kg.getOpenId() 返回 mock_openid_xxx？

你在普通浏览器里打开了页面。SDK 拿不到 App 注入的身份，进入了 mock 模式。用看购 App 打开就是真实值。

Q：同一个用户在我的两个应用里，openId 为什么不一样？

这是设计如此。openId 按「用户 × 应用」配对生成，避免不同开发者之间撞库。要在自己名下多个应用间识别同一个人，请用 unionId。

Q：能拿到用户的手机号或身份证吗？

不能。JSSDK 只提供 openId、unionId 和昵称、头像等公开资料。

Q：应用创建后能改域名吗？

可以，但改完 WebsiteKey 会重新生成，需要重新下载验证文件并放到新域名的根目录。改域名期间 kg.config 会失败。

Q：AppSecret 泄露了怎么办？

立即到「应用设置 → 安全中心」重置。重置后旧的 AppSecret 立刻失效，记得同步更新你服务器上的配置。

看购网页开发 · 起步指南 ​

一、起步前准备 ​

开通链路 ​

名词解释 ​

二、注册与实名认证 ​

2.1 下载看购 App 并注册 ​

2.2 完成实名认证 ​

三、主体认证 ​

3.1 主体认证挂在你的账号上 ​

3.2 办理认证 ​

四、登录开放平台 ​

4.1 运营者 ​

​

4.2 切换身份 和选择 h5App ​

五、创建你的第一个 H5APP ​

应用认证 ​

完成域名验证 ​

六、配置 H5 入口 ​

七、写第一个页面 ​

八、在看购 App 里打开它 ​

会话卡片 ​

直接打开链接 ​

九、接下来做什么 ​

附录：常见问题 ​