日期	版本	修订内容摘要
2023-09-07	v1.0.0	更新接口文档

微信小程序接入

1、注册激活产品

创蓝云智注册账号,进行认证，并激活。

2、接入说明

小程序原生语言接入

注意：

1. 请勿在“微信开发者工具”的“游客模式”下接入验证码。
2. 目前尚未支持 Skyline 渲染模式。

步骤 1：添加插件

1. 用管理员身份登录 微信公众平台，且需使用接入小程序的相关账号。
2. 选择设置 > 第三方设置 > 添加插件，在搜索框内输入关键字“腾讯验证码”查找插件，并单击添加，如下图所示。
   

   预览

步骤 2：集成插件

1. 引入验证码小程序插件。 使用验证码插件前，需要在 app.json 中声明验证码小程序插件，如下：

   复制成功
     {
           "plugins": {
               "captcha": {
                   "version": "2.0.0", //请选择小程序插件最新版本
                   "provider": "wx1fe8d9a3cb067a75"
               }
           }
      }

2. 引入验证码小程序组件。 需要在页面.json文件中需要引入自定义组件，js 代码如下：

   复制成功
     {
           "usingComponents": {
             "t-captcha": "plugin://captcha/t-captcha"
           }
      }

步骤 3：使用小程序插件

1. 使用原生小程序语言接入时，需要在自定义的.wxml文件中，使用验证码插件，wxml 代码如下：

   复制成功
      <!-- app-id：验证码CaptchaAppId, 从创蓝云智控制台中获取, 在行为验证码控制台页面内【行为验证码】>【应用管理】> 【验证ID】进行查看 -->
      <t-captcha
           id="captcha"
           app-id="小程序插件验证码CaptchaAppId"
           bindverify="handlerVerify"
           bindready="handlerReady"
           bindclose="handlerClose"
           binderror="handlerError" />
      <button bindtap='login'>登录</button>

• 组件参数说明：

  字段名	值类型	默认值	说明
  CaptchaAppId	String	无	验证码应用 ID
  lang	String	zh-CN	语言，可选 zh-CN、zh-TW、en
  themeColor	String	#1A79FF	主题色

• 组件事件说明：

  事件名	参数	说明
  ready	无	验证码准备就绪
  verify	{ret, ticket}	验证码验证完成
  close	{ret}	验证码弹框准备关闭
  error	无	验证码配置失败

• 组件方法说明

  方法名	说明
  show	展示验证码
  destroy	销毁验证码
  refresh	重置验证码

2. 在自定义的.js文件中，监听事件，代码如下：

   复制成功
      Page({
             data: {},
             login: function () {
                 this.selectComponent('#captcha').show()
                 // 进行业务逻辑，若出现错误需重置验证码，执行以下方法
                 // if (error) {
                 // this.selectComponent('#captcha').refresh()
                 // }
             },
             // 验证码验证结果回调
             handlerVerify: function (ev) {
                 // 如果使用了 mpvue，ev.detail 需要换成 ev.mp.detail
                 if(ev.detail.ret === 0) {
                     // 验证成功
                     console.log('ticket:', ev.detail.ticket)
                 } else {
                     // 验证失败
                     // 请不要在验证失败中调用refresh，验证码内部会进行相应处理
                 }
             },    
             // 验证码准备就绪
             handlerReady: function () {
                 console.log('验证码准备就绪')
             },    
             // 验证码弹框准备关闭
             handlerClose: function (ev) {
                 // 如果使用了 mpvue，ev.detail 需要换成 ev.mp.detail,ret为0是验证完成后自动关闭验证码弹窗，ret为2是用户主动点击了关闭按钮关闭验证码弹窗
                 if(ev && ev.detail.ret && ev.detail.ret === 2){
                     console.log('点击了关闭按钮，验证码弹框准备关闭');
                 } else {
                     console.log('验证完成，验证码弹框准备关闭');
                 }
             },
             // 验证码出错
             handlerError: function (ev) {
                 console.log(ev.detail.errMsg)
             }
        })

   注意

   业务客户端完成验证码接入后，服务端需二次核查验证码票据结果（未接入票据校验，会导致黑产轻易伪造验证结果，失去验证码人机对抗效果），详情请参见 接入票据校验(微信小程序)。

uni-app 前端框架接入

注意： 请勿在“微信开发者工具”的“游客模式”下接入验证码。

步骤 1：添加插件

1. 用管理员身份登录 微信公众平台，且需使用接入小程序的相关账号。
2. 选择设置 > 第三方设置 > 添加插件，在搜索框内输入关键字“腾讯验证码”查找插件，并单击添加，如下图所示。
   

   预览

步骤 2：集成插件

1. 引入验证码小程序插件。 使用验证码插件前，需要在 app.json 中声明验证码小程序插件，如下：

   复制成功
     {
           "plugins": {
               "myPlugin": {
                   "version": "2.0.0", //请选择小程序插件最新版本
                   "provider": "wx1fe8d9a3cb067a75"
               }
           }
      }

2. 引入验证码小程序组件。 需要在页面.json文件中需要引入自定义组件，js 代码如下：

   复制成功
     {
           "usingComponents": {
             "t-captcha": "plugin://captcha/t-captcha"
           }
      }

步骤 3：使用小程序插件

1. 使用原生小程序语言接入时，需要在自定义的.wxml文件中，使用验证码插件，wxml 代码如下：

   复制成功
      <!-- app-id：验证码CaptchaAppId, 从创蓝云智控制台中获取, 在行为验证码控制台页面内【行为验证码】>【应用管理】> 【验证ID】进行查看 -->
      <t-captcha
           id="captcha"
           app-id="小程序插件验证码CaptchaAppId"
           @verify="handlerVerify"
           @ready="handlerReady"
           @close="handlerClose"
           @error="handlerError" />
      <button @click="login">登录</button>

• 组件参数说明：

  字段名	值类型	默认值	说明
  CaptchaAppId	String	无	验证码应用 ID
  lang	String	zh-CN	语言，可选 zh-CN、zh-TW、en
  themeColor	String	#1A79FF	主题色

• 组件事件说明：

  事件名	参数	说明
  ready	无	验证码准备就绪
  verify	{ret, ticket}	验证码验证完成
  close	{ret}	验证码弹框准备关闭
  error	无	验证码配置失败

• 组件方法说明

  方法名	说明
  show	展示验证码
  destroy	销毁验证码
  refresh	重置验证码

2. 在自定义的.vue文件中，监听事件，代码如下：

   复制成功
      methods:{
           login: function () {
               this.selectComponent('#captcha').show()
               // 进行业务逻辑，若出现错误需重置验证码，执行以下方法
               // if (error) {
               // this.selectComponent('#captcha').refresh()
               // }
           },
           // 验证码验证结果回调
           handlerVerify: function (ev) {
               // 如果使用了 mpvue，ev.detail 需要换成 ev.mp.detail
               if(ev.detail.ret === 0) {
                   // 验证成功
                   console.log('ticket:', ev.detail.ticket)
               } else {
                   // 验证失败
                   // 请不要在验证失败中调用refresh，验证码内部会进行相应处理
               }
           },    
           // 验证码准备就绪
           handlerReady: function () {
               console.log('验证码准备就绪')
           },    
           // 验证码弹框准备关闭
           handlerClose: function (ev) {
               // 如果使用了 mpvue，ev.detail 需要换成 ev.mp.detail,ret为0是验证完成后自动关闭验证码弹窗，ret为2是用户主动点击了关闭按钮关闭验证码弹窗
               if(ev && ev.detail.ret && ev.detail.ret === 2){
                   console.log('点击了关闭按钮，验证码弹框准备关闭');
               } else {
                   console.log('验证完成，验证码弹框准备关闭');
               }
           },
           // 验证码出错
           handlerError: function (ev) {
               console.log(ev.detail.errMsg)
           }
      }

Taro 框架小程序插件接入示例

1. 在 app.config.ts 引入小程序插件。

复制成功

{
  "plugins": {
    "captcha": {
      "version": "2.1.0",
      "provider": "wx1fe8d9a3cb067a75"
    }
  }
}

2. 在需要加载验证码的页面配置插件，如 page/index/index.config.ts。

复制成功

{
  "usingComponents": {
    "t-captcha": "plugin://captcha/t-captcha"
  }
}

3. 在页面调用验证码，如 page/index/index.tsx。

复制成功

import { getCurrentInstance, PageInstance } from '@tarojs/taro';

export default function Index() {
  // 获取页面实例

  const { page } = getCurrentInstance();

  // 弹出验证码

  const handlerCaptchaShow = () => {
    const pageInstance = page as PageInstance;

    const captcha: any = pageInstance.selectComponent && pageInstance?.selectComponent('#captcha');

    try {
      captcha?.show();
    } catch (error) {
      // 进行业务逻辑，若出现错误需重置验证码，执行以下方法

      captcha?.refresh();
    }
  };

  // 验证码验证结果回调

  const handlerVerify = (ev) => {
    console.log('ret:', ev.detail);

    // 如果使用了 mpvue，ev.detail 需要换成 ev.mp.detail

    if (ev.detail.ret === 0) {
      // 验证成功

      console.log('ticket:', ev.detail.ticket);
    } else {
      // 验证失败
      // 请不要在验证失败中调用refresh，验证码内部会进行相应处理
    }
  };

  return (
    <View className='index'>
      <t-captcha id='captcha' appId='小程序插件验证码CaptchaAppId' onVerify={handlerVerify} />
      <Button onClick={handlerCaptchaShow}>弹出验证码</Button>
    </View>
  );
}

注意 业务客户端完成验证码接入后，服务端需二次核查验证码票据结果（未接入票据校验，会导致黑产轻易伪造验证结果，失去验证码人机对抗效果），详情请参见 [服务端接入> 微信小程序接入]。