---
order: 1
navTitle: 小程序
---
# SuccBI 与支付宝小程序集成

本文介绍如何将 SuccBI 移动应用与支付宝小程序集成。

## 技术原理介绍{#introduction}

SuccBI 移动应用本质上是 web 应用，需要使用小程序的[web-view](https://opendocs.alipay.com/mini/component/web-view)组件来展示。web-view 组件有一些限制：

1. 不支持个人小程序使用，仅支持企业小程序。
2. web-view 组件会自动铺满整个页面，覆盖其它组件。
3. 只能使用 https 域名，并且需要添加到小程序h5域名白名单中。

更多限制可查看官方文档。

## 准备工作{#preparation}

1. 准备好支付宝企业小程序帐号。
2. [配置H5域名](https://opendocs.alipay.com/mini/component/idfvg6)

## 嵌入到已有的小程序{#embedded}

1. 首先需要在已有的小程序中配置好H5域名。
2. 已有的小程序中需要添加一个 web-view 页面，将 web-wiew 地址设置为 SuccBI 的项目地址，还需要添加参数`:embedded=true`。例如：`https://demo.succbi.com/v5?:embedded=true`。

TODO 考虑单点登录

## 开发新的小程序{#new-miniprogram}

### 使用 SuccBI 小程序模版{#use-template}

1. 下载安装[小程序开发者工具](https://opendocs.alipay.com/mini/ide/download)
2. 下载[小程序模板代码](https://gitlab.succez.com/succsoft/alipayMiniprogram)`git clone git@gitlab.succez.com:succsoft/alipayMiniprogram.git`
3. 使用开发者工具打开项目，在项目根目录执行`npm install`.（可选，用于安装类型声明文件）
4. 修改`app.js`中的相关配置:

   ```javascript
    {
    	/**
    	 * 项目根地址，包括完整域名和contextpath，不以斜线结尾， 例如："https://demo.succbi.com/v5"，"https://demo.succbi.com/v5/contextpath"。
    	 * 注意: 需要在小程序中配置对应的h5域名。 https://opendocs.alipay.com/mini/component/idfvg6
    	 */
    	ROOT_URL: 'https://demo.succbi.com/v5',
    	/**
    	 * 首页地址，一般为移动应用的地址，以斜线加项目名开头，不包括域名和contextPath，例如："/DEMO/app/DEMO.app/移动展示.mpg"。
    	 * 注意：如果系统配置了移动端首页，则不需要配置这个。
    	 */
    	INDEX_PATH: '/DEMO/app/DEMO.app'
    }
   ```

#### 小程序内的页面说明

1. `pages/index`: 小程序的首页，用于展示系统移动应用的 web-view 页面，一般不需要修改。
2. `pages/page`: 二级 web-view 页面，打开应用中的下级页面时使用的 web-view，小程序中**必须**有该页面，且不能做任何修改。

### 微信认证登录{#login-with-wechat}

TODO

### 手机号码认证登录{#login-with-phone}

TODO

### 账号密码登录{#login-with-password}

TODO

### 切换登录方式{#switch-login-type}

TODO

### 扫码授权 PC 登录{#authorize-pc-login}

TODO

### 注销登录{#logout}

可直接使用注销交互，系统会自动处理小程序中的注销，内部通过调用 jssdk 跳转到首页，并传参`logout=true`:

## 小程序功能{#features}

### 扫码{#scan-qrcode}

可直接使用扫码交互，系统会使用 jssdk 调用原生接口进行扫码。

### 下载文件{#download}

TODO

### 返回上页{#navigate-back}

可直接使用返回上页交互，系统会自动判断是否需要返回到首页。

## 常见问题{#FAQ}

### ios端打开页面的时候弹出异常对话框提示`“Script Error”`{#FAQ-1}

可能原因有：

1. 没有为返回的html指定初始展示大小

   解决方案为： 针对返回给浏览器展示的html，在`head`标签中，添加

   ```html
   <meta name="viewport" content="initial-scale=1.0">
   ```

   猜测：由于html中没有指定页面初始展示比例，支付宝浏览器引擎在初始化页面在应用css时导致页面产生了一次缩放，出现的bug。给页面指定初始展示比例用于在浏览器引擎应用css缩放前完成对缩放功能的初始化。

   截止到`2020年3月11日`，这个异常可以被被`window.onerror`监听到错误，也就是现在会根据SuccBI默认的错误提示对话框展示`Script Error` 但是无法获取到堆栈信息。

   支付宝页面弹窗提示`“contentList[item].split is not a function. (In 'contentList[item].split("=")', 'contentList[item].split' is undefined)”`与这个问题类似，都可以通过在html指定初始展示大小来解决。

2. html或者html 中引用到的js文件有语法错误。