字节跳动小程序支持四种验证码类型：

* 智能无感知
* 滑块拼图
* 文字点选
* 图标点选

## 平台支持
字节跳动小程序支持最低基础库版本为 1.90.0，对应的抖音版本为 13.5，头条的版本为 7.9.6。

## 环境准备
### 开发环境
* 申请字节跳动开发者账号
* 安装字节跳动开发者工具

### 项目开发配置
请在开发设置-服务器域名白名单添加如下域名：
c.dun.163.com、c.dun.163yun.com

## 资源集成
* 下载资源
请将[下载组件](https://nos.netease.com/cloud-website-bucket/0c0fc9e15f57d5d95d486289169cee1c.zip)，将解压后的组件放置在 components 或其他目录下（字节跳动小程序暂不支持 npm 引入第三方包）

* 在使用页对应的 json 中引入验证码组件
```json
{
  "usingComponents": {
    "ne-captcha": "path-to-component/ne-captcha/index"
  }
}
```

## 快速调用示例
在 index 页面集成验证码：
* index.json
    ```
    {
      "usingComponents": {
        "ne-captcha": "path-to-component/ne-captcha/index"
      }
    }
    ```

* index.ttml
    ```
    <view>
      <ne-captcha
        id="captcha"
        captcha-id="业务ID"
        width="640rpx"
        bindverify="handleCaptchaVerify"></ne-captcha>
      <button bindtap="tryToVerify">点击验证</button>
    </view>
    ```
* index.js
    ```
    Page({
        tryToVerify () {
            this.selectComponent('#captcha', res => {
                res && res.popup()
            })
        },
        handleCaptchaVerify (ev) {
            const [err, validate] = ev.detail
            if (!err) {
                // TODO
                // 验证成功，进行后续的业务逻辑，如登录等
                // validate 用于服务端二次验证
            }
        }
    })
    ```

## SDK方法说明
### 使用组件
字节跳动小程序验证码提供验证码组件，在使用的页面引入即可。

#### 代码说明
* ttml
```
    <ne-captcha id="captcha" captcha-id="业务ID"></ne-captcha>
```                                                                               

* 获取组件实例
```js
    this.selectComponent('#captcha', res => {
        this.captchaIns = res
    }) // captcha为元素id
```

#### 组件属性说明
|    属性   |          类型        |是否必填|默认值|描述|
|-----------|---------------------|-------|------|------------|
|captchaId |String  |是 |无 |验证码业务ID |
|width | Number &#124;String |否 |'auto' |验证按钮宽度；类型为 String 时，支持后缀 `rpx`、`px`、`rem`；类型为 Number 时，内部会将其转换成 `rpx` 单位的值 |
|lang |String |否 |zh-CN |验证码使用的语言 |
|timeout |Number |否 |6000 |请求超时时间，单位为毫秒 |
|customStyles |Object |否 |null |自定义样式，详见自定义样式配置 |
|customTexts |Object |否 |null |自定义文本，用户可指定文本使用自定义，详见自定义文案配置 |
|extraData |String |否 |无 |如果需要在 check 阶段透传业务数据，可以使用 extraData 配置。当调用二次校验结果接口时，会原样返回该字段，详见[后端响应参数]() |
|bindinit |Eventhandle |否 |无 |验证码配置（初始化）成功触发的事件 |
|binderror |Eventhandle |否 |无 |验证码配置失败触发的事件 |
|bindready |Eventhandle |否 |无 |验证码准备就绪（可进行验证）触发的事件 |
|bindverify |Eventhandle |否 |无 |验证码一次验证完成触发的事件 |
|bindclose |Eventhandle |否 |无 |验证码弹出关闭触发的事件 |

*注意：自定义功能仅高版本套餐支持，详情请咨询[客服](https://dun.163.com/kefu)*

* 自定义样式：customStyles

为更好地理解自定义样式相关内容，请先了解我们对易盾验证码弹框界面组成部分的定义
![验证码结构](https://nos.netease.com/yidun/captcha_4050171811d86e275699d3cfcb341641.png?ynotemdtimestamp=1628835459388)

自定义样式数据结构如下：
```
- customStyles (Object)
    - imagePanel (Object)
        - borderRadius (String): imagePanel 的圆角大小
    - controlBar (Object)
        - borderRadius (String): controlBar 的圆角大小
        - height (String): controlBar 的高度
    - gap (String): imagePanel 和 controlBar 的间隔
    - popTitle (Object)
        - height (String): 弹框头部高度
    - popPadding (String): 弹框体内边距
```
使用示例：
```
    <ne-captcha
        captcha-id="业务ID"
        width="640rpx"
        custom-styles="{{customStyles}}"></ne-captcha>
```
```js
    Page({
        data: {
            customStyles: {
                imagePanel: {
                    borderRadius: '2rpx'
                },
                controlBar: {
                    height: '80rpx'
                }
            }
        }
    })
```

* 自定义文案：customTexts

| 属性 | 原文案（简体中文） |
| ---- | ---------------- |
|LOADING |加载中... |
|LOAD_FAIL |加载失败 |
|VERIFY_SUCCESS |验证成功 |
|VERIFY_ERROR |验证失败，请重试 |
|VERIFY_OUT_OF_LIMIT |失败过多，点此重试 |
|CLICK_BUTTON |点此进行验证 |
|CLICK_IN_TURN |请依次点击 |
|SLIDE_TIP |向右拖动滑块填充拼图 |
|POPUP_TITLE |请完成安全验证 |

使用示例：
```
<ne-captcha
    captcha-id="业务ID"
    width="640rpx"
    custom-texts="{{customTexts}}"></ne-captcha>
```
```
    Page({
        data: {
            customTexts: {
                LOADING: '加载中，请耐心等待',
                LOAD_FAIL: '加载失败，刷新重试'
            }
        }
    })
```

* 多语言：lang
支持语音种类见下表：

| 语种 | 简体中文 | 英语 | 繁体中文 | 日语 | 韩语 | 泰语 | 越南语 | 法语 | 俄语 |
| ---- | -------- | ---- | -------- | ---- | ---- | ---- | ------ | ---- | ---- |
| lang | zh-CN | en | zh-TW | ja | ko | th | vi | fr | ru |

#### 事件参数说明：
* bindverify - 事件对象（event）说明：
```
- event (Object)
    - detail (Array)
        - error (Error): 验证失败的错误信息
        - validate (String): 二次验证信息
```

### 进行验证码验证
验证需区分验证码的类型，若验证码为常规类型，则调用 popup 方法进行验证；若验证码为智能无感知，则调用 verify 方法进行验证。

#### 代码说明
* 常规验证码
```js
    this.captchaIns.popup()  // this.captchaIns 为验证码组件实例
```

* 智能无感知
```js
    this.captchaIns.verify() // this.captchaIns 为验证码组件实例
```

### 刷新验证码（可选）

当上一轮验证成功后，若业务需要重置验证码，重新进行验证时，可以调用 `reset` 方法。

**注意：请不要在验证失败时调用，失败时验证码会自动刷新。**

#### 代码说明
```js
    this.captchaIns.reset() // this.captchaIns 为验证码组件实例
```

## 错误码
| code | 含义 |
|------|------|
| 200  |校验未通过，是因为业务错误，包括超限 |
| 501  |接口请求失败，包括网络原因等 |
| 503  |图片请求失败 |
| 1000 |未知错误 |