实名认证

客户端接入

更新时间：2024-09-19 17:02:32

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

一、Web 客户端接入

1、注册激活产品

创蓝云智注册账号,进行认证，并激活，之后在【应用管理】创建应用

2、接入说明

步骤 1：动态引入验证码 JS

Web 页面需动态引入验证码 JS，在业务需要验证时，唤起验证码进行验证。

<script src="https://captcha.253.com/TCaptcha.js"></script>

注意：

必须动态引入验证码 JS。如使用本地缓存，或通过其他手段规避动态加载，会导致验证码无法正常更新，对抗能力无法保证，甚至引起误拦截。

3、代码示例

以下代码示例，单击验证，激活验证码，并弹窗展示验证结果。

<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="UTF-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Web 前端接入示例</title>
    <!-- 验证码程序依赖(必须)。请勿修改以下程序依赖，如使用本地缓存，或通过其他手段规避加载，会导致验证码无法正常更新，对抗能力无法保证，甚至引起误拦截。 -->
    <script src="https://captcha.253.com/TCaptcha.js"></script>
</head>

<body>
    <button id="CaptchaId" type="button">验证</button>
</body>

<script>

    // 定义回调函数
    function callback(res) {
        // 第一个参数传入回调结果，结果如下：
        // ret         Int       验证结果，0：验证成功。2：用户主动关闭验证码。
        // ticket      String    验证成功的票据，当且仅当 ret = 0 时 ticket 有值。
        // CaptchaAppId       String    验证码应用ID。
        // bizState    Any       自定义透传参数。
        // randstr     String    本次验证的随机串，后续票据校验时需传递该参数。
        console.log('callback:', res);
    }

    //初始化对象
    var captcha = new TencentCaptcha('你的验证码CaptchaAppId', callback, {});

    // 定义验证码触发事件
    document.getElementById('CaptchaId').onclick = function(){
      captcha.show();
    }
</script>

</html>

4、创建验证码对象

引入验证码 JS 后，验证码会在全局注册一个 TencentCaptcha 类，业务方可以使用这个类自行初始化验证码，并对验证码进行显示或者隐藏。

构造函数

new TencentCaptcha(CaptchaAppId, callback, options);

参数说明

参数名	值类型	说明
CaptchaAppId	String	验证码 CaptchaAppId 如果未创建过验证，请先新建验证。注意：不可使用客户端类型为小程序的 CaptchaAppId，会导致数据统计错误。
callback	Function	验证码回调函数，详情请参见 callback 回调函数。
options	Object	验证码外观配置参数, 详情请参见 options 外观配置参数。

callback 回调函数

验证结束后，会调用业务传入的回调函数，并在第一个参数中传入回调结果。回调结果字段说明如下：

字段名	值类型	说明
ret	Int	验证结果，0：验证成功。2：用户主动关闭验证码。
ticket	String	验证成功的票据，当且仅当 ret = 0 时 ticket 有值。
CaptchaAppId	String	验证码应用 ID。
bizState	Any	自定义透传参数。
randstr	String	本次验证的随机串，后续票据校验时需传递该参数。
errorCode	Number	错误 code ，详情请参见回调函数 errorCode 说明。
errorMessage	String	错误信息。

回调函数 errorCode 说明

errorCode	说明
1001	TCaptcha.js 加载错误
1002	调用 show 方法超时
1003	中间 js 加载超时
1004	中间 js 加载错误
1005	中间 js 运行错误
1006	拉取验证码配置错误/超时
1007	iframe 加载超时
1008	iframe 加载错误
1009	jquery 加载错误
1010	滑块 js 加载错误
1011	滑块 js 运行错误
1012	刷新连续错误 3 次
1013	验证网络连续错误 3 次

options 外观配置参数

options 参数用于对验证码进行定制外观设置，默认可以设置为空。

*注意：

1、验证码弹窗内部不支持调整样式大小，如果需要调整，可在弹窗最外层用 class=tcaptcha-transform 的元素设置 transform:scale();。验证码更新可能会改变元素的 id，class 等属性，请勿依赖其他验证码元素属性值覆盖样式。

2、如果手机原生端有设置左右滑动手势，需在调用验证码 show 方法前禁用，验证完成后再打开，防止与验证码滑动事件冲突。

配置名	值类型	说明
bizState	Any	自定义透传参数，业务可用该字段传递少量数据，该字段的内容会被带入 callback 回调的对象中。
enableDarkMode	Boolean \| String	开启自适应深夜模式: {"enableDarkMode": true} 强制深夜模式: {"enableDarkMode": 'force'}
sdkOpts	Object	示例 {"width": 140, "height": 140} 仅支持移动端原生 webview 调用时传入，用来设置验证码 loading 加载弹窗的大小（注意，并非验证码弹窗大小）。
ready	Function	验证码加载完成的回调，回调参数为验证码实际的宽高： {"sdkView": { "width": number, "height": number }} 该参数仅为查看验证码宽高使用，请勿使用此参数直接设定宽高。
needFeedBack	Boolean \| String	隐藏帮助按钮或自定义帮助按钮链接。隐藏帮助按钮: {"needFeedBack": false } 自定义帮助链接: {"needFeedBack": 'url 地址' }
loading	Boolean	是否在验证码加载过程中显示loading框。不指定该参数时，默认显示loading框。显示 loading 框: {"loading": true};不显示 loading 框: {"loading": false} （展示方式为嵌入式时不支持配置）
userLanguage	String	指定验证码提示文案的语言，优先级高于控制台配置。支持传入值同 navigator.language 用户首选语言，大小写不敏感。详情参见 userLanguage 配置参数。
type	String	定义验证码展示方式。popup（默认）弹出式，以浮层形式居中弹出展示验证码。embed 嵌入式，以嵌入指定容器元素中的方式展示验证码。

userLanguage 配置参数

参数名	说明
zh-cn	简体中文
zh-hk	繁体中文（中国香港）
zh-tw	繁体中文（中国台湾）
en	英文
ar	阿拉伯语
my	缅甸语
fr	法语
de	德语
he	希伯来语
hi	印地语
id	印尼语
it	意大利语
ja	日语
ko	朝鲜语
lo	老挝语
ms	马来语
pl	波兰语
pt	葡萄牙语
ru	俄语
es	西班牙语
th	泰语
tr	土耳其语
vi	越南语

5、调用验证码实例方法

TencentCaptcha 的实例提供一些操作验证码的常用方法：

方法名	说明	传入参数	返回内容
show	显示验证码，可以反复调用。	无	无
destroy	隐藏验证码，可以反复调用。	无	无
getTicket	获取验证成功后的 ticket。	无	Object:{"CaptchaAppId":"","ticket":""}

二、APP客户端接入

1、Android 接入

Android 接入主要流程

在 Android 端利用 WebView 引入 H5页面。H5 页面接入验证码，详情请参见 Web 客户端接入。
在 H5 页面中，通过调用验证码 JS，渲染验证页面，并将 JS 返回的参数值传到 Android App 业务端。
Android App 业务端把相关参数（票据 ticket、随机数等）传入业务侧后端服务进行票据验证。

Android 接入详细步骤

1.在项目的工程中，新建一个 Activity 并导入 WebView 组件所需的包。

import android.webkit.WebView;
import android.webkit.WebSettings;
import android.webkit.WebViewClient;
import android.webkit.WebChromeClient;

2.添加相关权限，如开启网络访问权限以及允许 App 进行非 HTTPS 请求等。

<uses-permission android:name="android.permission.INTERNET"/>
<application android:usesCleartextTraffic="true">...</application>

3.在 Activity 的布局文件中，添加 WebView 组件。

<WebView
android:id="@+id/webview"
android:layout_height="match_parent"
android:layout_width="match_parent"
/>

4.在项目的工程中，添加自定义 JavascriptInterface 文件，并定义一个方法用来获取相关数据。

import android.webkit.JavascriptInterface;
public class JsBridge {
@JavascriptInterface
public void getData(String data) {
System.out.println(data);
}
}

5.在 Activity 文件中，加载相关 H5 业务页面。

public class MainActivity extends AppCompatActivity {
private WebView webview;
private WebSettings webSettings;

@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
initView();
}

private void initView() {
webview = (WebView) findViewById(R.id.webview);
webSettings = webview.getSettings();
webSettings.setUseWideViewPort(true);
webSettings.setLoadWithOverviewMode(true);
// 禁用缓存
webSettings.setCacheMode(WebSettings.LOAD_NO_CACHE);
webview.setWebViewClient(new WebViewClient(){
@Override
public boolean shouldOverrideUrlLoading(WebView view, String url) {
view.loadUrl(url);
return true;
}
});
// 开启js支持
webSettings.setJavaScriptEnabled(true);
webview.addJavascriptInterface(new JsBridge(), "jsBridge");
// 也可以加载本地html(webView.loadUrl("file:///android_asset/xxx.html"))
webview.loadUrl("https://x.x.x/x/");
}
}

6.在 H5 业务页面中接入验证码，详情请参见 Web 客户端接入

2、iOS 接入

iOS 接入主要流程

在 iOS 中打开 WebView，通过 JSBridge 触发 HTML 页面，同时注入方法，供 HTML 调用传入验证结果。
在 HTML 页面中接入验证码，详细请参见 Web 客户端接入，通过调用验证码 JS，渲染验证页面，并调用 iOS 注入的方法传入验证结果。
通过 JSBridge 将验证结果返回到 iOS，并把相关参数（票据 ticket、随机数等）传入业务侧后端服务进行票据验证。

iOS 接入的详细操作步骤

1.在控制器或 view 中导入 WebKit 库。

#import <WebKit/WebKit.h>

2.创建 WebView 并渲染。

-(WKWebView *)webView{
if(_webView == nil){    
 //创建网页配置对象
 WKWebViewConfiguration *config = [[WKWebViewConfiguration alloc] init];
 // 创建设置对象
 WKPreferences *preference = [[WKPreferences alloc]init];
 //设置是否支持 javaScript 默认是支持的
 preference.javaScriptEnabled = YES;
 // 在 iOS 上默认为 NO，表示是否允许不经过用户交互由 javaScript 自动打开窗口
 preference.javaScriptCanOpenWindowsAutomatically = YES;
 config.preferences = preference;      
 //这个类主要用来做 native 与 JavaScript 的交互管理
 WKUserContentController * wkUController = [[WKUserContentController alloc] init];
 //注册一个name为jsToOcNoPrams的js方法 设置处理接收JS方法的对象
 [wkUController addScriptMessageHandler:self  name:@"jsToOcNoPrams"];
 [wkUController addScriptMessageHandler:self  name:@"jsToOcWithPrams"]; 
 config.userContentController = wkUController;     
 _webView = [[WKWebView alloc] initWithFrame:CGRectMake(0, 0, SCREEN_WIDTH, SCREEN_HEIGHT) configuration:config];
 // UI 代理
 _webView.UIDelegate = self;
 // 导航代理
 _webView.navigationDelegate = self;        
 //此处即需要渲染的网页
 NSString *path = [[NSBundle mainBundle] pathForResource:@"JStoOC.html" ofType:nil];
 NSString *htmlString = [[NSString alloc]initWithContentsOfFile:path encoding:NSUTF8StringEncoding error:nil];
 [_webView loadHTMLString:htmlString baseURL:[NSURL fileURLWithPath:[[NSBundle mainBundle] bundlePath]]];       
}
return _webView;
}
[self.view addSubview:self.webView];

3.代理方法，处理一些响应事件。

// 页面开始加载时调用
-(void)webView:(WKWebView *)webView didStartProvisionalNavigation:(WKNavigation *)navigation {
}
// 页面加载失败时调用
-(void)webView:(WKWebView *)webView didFailProvisionalNavigation:(null_unspecified WKNavigation *)navigation withError:(NSError *)error {
[self.progressView setProgress:0.0f animated:NO];
}
// 当内容开始返回时调用
-(void)webView:(WKWebView *)webView didCommitNavigation:(WKNavigation *)navigation {
}
// 页面加载完成之后调用
-(void)webView:(WKWebView *)webView didFinishNavigation:(WKNavigation *)navigation {
[self getCookie];
}
//提交发生错误时调用
-(void)webView:(WKWebView *)webView didFailNavigation:(WKNavigation *)navigation withError:(NSError *)error {
[self.progressView setProgress:0.0f animated:NO];
}
// 接收到服务器跳转请求即服务重定向时之后调用
-(void)webView:(WKWebView *)webView didReceiveServerRedirectForProvisionalNavigation:(WKNavigation *)navigation {
}

4.JS 将参数传给 OC。

<p style="text-align:center"> <button id="btn2" type = "button" onclick = "jsToOcFunction()"> JS调用OC：带参数  </button> </p>
function jsToOcFunction()
{
window.webkit.messageHandlers.jsToOcWithPrams.postMessage({"params":"res.randstr"});
}

5.将渲染好的 WebView 展示在视图上，调用验证码服务，将数据传给客户端。

-(void)userContentController:(WKUserContentController *)userContentController didReceiveScriptMessage:(WKScriptMessage *)message{
//此处message.body即传给客户端的json数据
//用message.body获得JS传出的参数体
NSDictionary * parameter = message.body;
//JS调用OC
if([message.name isEqualToString:@"jsToOcWithPrams"]){
//在此处客户端得到js透传数据 并对数据进行后续操作
parameter[@"params"]
}
}

三、微信小程序接入

1、注册激活产品

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

2、接入说明

小程序原生语言接入

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

步骤 1：添加插件

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

步骤 2：集成插件

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

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

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

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

步骤 3：使用小程序插件

使用原生小程序语言接入时，需要在自定义的.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 重置验证码

字段名	值类型	默认值	说明
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	重置验证码

在自定义的.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：添加插件

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

步骤 2：集成插件

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

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

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

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

步骤 3：使用小程序插件

使用原生小程序语言接入时，需要在自定义的.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 重置验证码

字段名	值类型	默认值	说明
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	重置验证码

在自定义的.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)
        }
   }

注意

没有更多了

上一篇：操作指南

下一篇：服务端接入

文档目录

收缩

注册登录

新客获客

老客激活

金融行业

游戏行业

电商行业

餐饮行业

私有云

热门搜索

中国站

国际站

实名认证

客户端接入

一、Web 客户端接入

1、注册激活产品

2、接入说明

3、代码示例

4、创建验证码对象

构造函数

callback 回调函数

options 外观配置参数

5、调用验证码实例方法

二、APP客户端接入

1、Android 接入

2、iOS 接入

三、微信小程序接入

1、注册激活产品

2、接入说明

小程序原生语言接入

步骤 1：添加插件

步骤 2：集成插件

步骤 3：使用小程序插件

uni-app 前端框架接入

步骤 1：添加插件

步骤 2：集成插件

步骤 3：使用小程序插件