验证码
有奖捉虫：办公协同&微信生态&物联网文档专题 HOT
文档中心 > 验证码 > 接入指引 > 客户端接入 > 微信小程序接入

微信小程序接入

最近更新时间：2024-04-11 17:31:31

我的收藏

本页目录：

注意：
为了提升验证码产品的性能和稳定性，腾讯验证码微信小程序插件已经升级至2.1.0版本。如果您有需求，可以按照以下方案进行接入。在新版本的插件中，我们将优化风险控制能力、用户体验和验证类型等功能。

前提条件

客户端接入前，需完成新建验证，并在验证列表获取所需的 CaptchaAppId 以及 AppSecretKey。步骤如下：
1. 登录 验证码控制台，左侧导航栏选择图形验证 > 验证管理，进入验证管理页面。
2. 单击新建验证，根据业务场景需求，设置验证名称、客户端类型、验证方式等参数。
3. 单击确定，完成新建验证，即可在验证列表中查看验证码 CaptchaAppId 及 AppSecretKey。

小程序原生语言接入

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

示例下载

代码示例：单击验证，激活验证码，并弹窗展示验证结果。
完整示例请下载：小程序验证码接入示例。

步骤1：添加插件

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




步骤2：集成插件

1. 引入验证码小程序插件。 使用验证码插件前，需要在 app.json 中声明验证码小程序插件，如下：
{
     "plugins": {
         "captcha": {
             "version": "2.1.0", //请选择小程序插件最新版本
             "provider": "wx1fe8d9a3cb067a75"
         }
     }
}
2. 引入验证码小程序组件。 需要在页面.json文件中需要引入自定义组件，js 代码如下：
{
     "usingComponents": {
       "t-captcha": "plugin://captcha/t-captcha"
     }
}

步骤3：使用小程序插件

1. 使用原生小程序语言接入时，需要在自定义的.wxml文件中，使用验证码插件，wxml 代码如下：
<!-- app-id：验证码CaptchaAppId, 从腾讯云的验证码控制台中获取, 在验证码控制台页面内【图形验证】>【验证列表】进行查看 -->
<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": {
         "captcha": {
             "version": "2.1.0", //请选择小程序插件最新版本
             "provider": "wx1fe8d9a3cb067a75"
         }
     }
}
2. 引入验证码小程序组件。 需要在页面.json文件中需要引入自定义组件，js 代码如下：
{
     "usingComponents": {
       "t-captcha": "plugin://captcha/t-captcha"
     }
}

步骤3：使用小程序插件

1. 使用 uni-app 框架接入时，需要在自定义的 .vue 中使用验证码插件，代码如下：
<!-- app-id：验证码CaptchaAppId, 从腾讯云的验证码控制台中获取, 在验证码控制台页面内【图形验证】>【验证列表】进行查看 -->
<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 文件中，监听事件，Vue2代码如下：
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)
     }
}
Vue3代码如下：
<script lang="ts" setup>
import { getCurrentInstance } from 'vue'
// 获取组件实例
const instance: any = getCurrentInstance()
const login = () => {
  instance.ctx.selectComponent('#captcha').show()
  // 进行业务逻辑，若出现错误需重置验证码，执行以下方法
  // if (error) {
  // instance.ctx.selectComponent('#captcha').refresh()
  // }
}
// 验证码验证结果回调
const handlerVerify = (ev) => {
  // 如果使用了 mpvue，ev.detail 需要换成 ev.mp.detail
  if (ev.detail.ret === 0) {
    // 验证成功
    console.log('ticket:', ev.detail.ticket)
  } else {
    // 验证失败
    // 请不要在验证失败中调用refresh，验证码内部会进行相应处理
  }
}
// 验证码准备就绪
const handlerReady = () => {
  console.log('验证码准备就绪')
}
// 验证码弹框准备关闭
const handlerClose = (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('验证完成，验证码弹框准备关闭')
  }
}
// 验证码出错
const handlerError = (ev) => {
  console.log(ev.detail.errMsg)
}
</script>

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>
  );
}

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

常见问题

详情参见 接入相关问题。

更多信息

您可以登录 验证码控制台，在页面右上角单击快速咨询，了解更多详细信息。
中国站