tencent cloud

验证码

动态与公告
产品动态
产品公告
产品简介
产品概述
产品优势
应用场景
购买指南
接入指引
客户端接入
服务端接入
与 WAF 服务提供方集成
JS 迁移指引
操作指南
验证管理
验证统计
API 文档
History
Introduction
API Category
Making API Requests
Server APIs
Error Codes
业务容灾方案
业务容灾方案(Web 及 APP)
常见问题
计费相关
功能相关
接入相关
相关协议
Service Level Agreement
隐私政策
数据处理和安全协议
联系我们
词汇表

安卓客户端 SDK 接入

PDF
聚焦模式
字号
最后更新时间: 2025-12-01 10:37:28

服务流程图



准备工作

隐私设置

隐私协议链接:隐私协议|验证码

在您将本 SDK 产品适配、集成或装载到您的产品、应用或服务前,您应仔细阅读并同意我们公示的相关服务协议、本规则及/或第三方开发者合规指南(或具有同样性质的相关法律文件), 并对您适配、集成或装载本 SDK 产品的产品的收集、使用个人信息情况进行合规自查。

如果您不同意隐私协议的任何内容,应立即停止接入及使用 SDK 产品和/或相关服务,同时,您应仅在获得终端用户的同意后使用本 SDK 产品并处理终端用户的个人信息,在获得终端用户的同意前,不应启用或初始化本 SDK。

验证码 CaptchaAppid

在您接入本 SDK 时依赖验证码业务 ID-CaptchaAppid,可通过腾讯云控制台 验证管理 对应获取,不输入 SDK 将无法正常工作。如您不存在相应的CaptchaAppid,请走腾讯云控制台新建。后续在验证码初始化设置必填参数设置时将会使用到,即 setCaptchaAppid(验证码 CaptchaAppid)。

Android SDK 接入

1. 集成方式
在 AndroidMainfest 中配置增加:
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
在 proguard 中增加:
-keep class com.**.TNative$aa { public *; }
-keep class com.**.TNative$aa$bb { public *; }
-keep class com.**.TNative$bb { *; }
-keep class com.**.TNative$bb$I { *; }
2. AAR 集成
将 aar 文件拷贝到工程的 libs 目录下,并设置依赖。在 build.gradle 文件中添加。
dependencies {
implementation fileTree(dir: 'libs', include: ['*.aar'])
}
defaultConfig {
ndk {
abiFilters "armeabi-v7a", "arm64-v8a"
}
}
根据实际情况选择 armeabi-v7a 或 arm64-v8a,暂不支持 x86和 x86_64架构。

验证码集成

声明显示验证码 tcaptchaWebview
<WebView
android:id="@+id/tcaptchaWebview"
android:layout_width="match_parent"
android:layout_height="match_parent"/>
验证码初始化及调用示例
// 初始化
TencentCaptchaConfig.BuilderconfigBuilder =new
TencentCaptchaConfig.Builder(getApplicationContext(),
newITencentCaptchaPrivacyPolicy(){...},
newICaptchaDeviceInfoProvider(){...});
RetCoderet =TencentCaptcha.init(config.build());
...
//必填参数
TencentCaptchaParam.BuildertencentCaptchaBuilder =new
TencentCaptchaParam.Builder
()
.setWebView(tcaptchaWebView)
.setCaptchaAppid(验证码CaptchaAppid);
// 业务start
TencentCaptcha.start(callback,tencentCaptchaBuilder.build());
验证码回调返回示例
TencentCaptchaCallback callback = new TencentCaptchaCallback() {
@Override
public void finish(RetCode ret, JSONObject resultObject) {...}

@Override
public void exception(Throwable t) {...}
};

SDK 类说明

主要类说明
说明
TencentCaptcha
SDK 主入口类
TencentCaptchaConfig
SDK 初始化配置
TencentCaptchaCallback
SDK 结果回调
TencentCaptchaParam
SDK 验证码入参
TencentCaptcha类(主入口)接口说明
/***
使用构建好的配置进行初始化
*
* @param TencentCaptchaConfig
* @return RetCode
*/
RetCode init(TencentCaptchaConfig);
/**
* 开始验证码检测
*
* @param TencentCaptchaCallback
* @param TencentCaptchaParam
* @return RetCode
*/
RetCode start(TencentCaptchaCallback, TencentCaptchaParam);
/**
* 中断检测流程
*/
void stop();

TencentCaptchaConfig 类(初始化配置)接口说明

使用 Builder 方式创建, 支持链式调用。
/**
* 创建TencentCaptcha.Builder对象。
*
* @param Context
* @param ITencentCaptchaPrivacyPolicy接口实例,【必须传入实现】,调用SDK任何接口都会通过该实例询问用户是否已经同意隐私条款
* @param ICaptchaDeviceInfoProvider接口实例,传入ANDROIDID,用于设备标识符本身的有效性校验,并甄别设备环境异常,以识别设备风险*/
*/
Builder(Context, ITencentCaptchaPrivacyPolicy,
ICaptchaDeviceInfoProvider);
TencentCaptchaCallback类(结果回调)接口说明
/**
* 验证码校验结束时回调,通知宿主获取校验票据等信息。
*
* @param RetCode,RetCode非OK的时候,请参考【RetCode值】章节
* @param JSONObject,RetCode为OK时,返回JSONObject信息说明请参考【JSONObject返回值】章节
*/
void finish(RetCode, JSONObject);
/**
* SDK工作线程发生异常时回调
*
* @param Throwable
*/
void exception(Throwable);
TencentCaptchaParam类(入参)接口说明
启动验证码的参数类。
/**
* 创建TencentCaptchaParam.Build对象
*
* @return TencentCaptchaParam
*/
TencentCaptchaParam build();
/**
* 设置验证码CaptchaAppid,走腾讯云控制台对应获取,不输入SDK无法正常工作
*
* @param String, 验证码CaptchaAppid
* @return Build
*/
Builder setCaptchaAppid(String);
/**
* 设置显示验证码的WebView
*
* @param webView
* @return Builder
*/
Builder setWebView(WebView);
注意:

示例代码

创建 SDK 配置构造器

TencentCaptchaConfig.Builder configBuilder = new
TencentCaptchaConfig.Builder(
getApplicationContext(),
new ITencentCaptchaPrivacyPolicy() {
@Override
public boolean userAgreement() {
// 是否授权通过
// true标识授权通过,可正常使用sdk
// false表示未授权,后续调用start方法会抛出异常
return false;
}
},
new ICaptchaDeviceInfoProvider() {
@Override
public String getAndroidId() {
return androidId; // 获取AndroidId实现
}
}
);

初始化 SDK 配置构造器

// 初始化SDK
RetCode ret = TencentCaptcha.init(configBuilder.build());
if(ret == RetCode.OK) {
// 初始化成功
} else {
// 初始化失败
log.error("ret code: " + ret.getCode() + " msg:" + ret.getMsg()); }

实现验证码回调

TencentCaptchaCallback callback = new TencentCaptchaCallback() {
@Override
public void finish(RetCode ret, JSONObject resultObject) {
if (ret == RetCode.OK) {
// 成功,执行业务逻辑
} else {
// 失败
log.error("code:" + ret.getCode() + " msg:" + ret.getMsg());
}
}
@Override
public void exception(Throwable t) {
// 异常
t.printStackTrace();
}
};

创建验证码入参

TencentCaptchaParam.Builder paramBuilder = new
TencentCaptchaParam.Builder()
.setWebView(tcaptchaWebView) //必填,验证码显示webview
.setCaptchaAppid("CaptchaAppid"); // 必填,验证码CaptchaAppid

启动验证码

TencentCaptcha.start(callback, paramBuilder.build());

中断验证码(一般在界面退出时调用)

@Override
protected void onPause() {
super.onPause();
TencentCaptcha.stop();}

RetCode(验证码校验结束时回调返回结果值)

RetCode方法

/**
* 获取错误码
*
* @return int
*/
int getCode();
/**
* 获取详细的错误信息
*
* @return String
*/
String getMsg();

RetCode值

RetCode值
code
说明
OK
0
成功,表示接收校验结果信息成功,具体判断还要结合 JSONObject 内容。
INIT_FAILED
1
初始化失败
NOT_INIT
2
未初始化
INVALID_PARAMS
3
入参非法
INVALID_WEBVIEW
4
webview为空
CAPTCHA_RETDATA_EMPTY
5
验证码返回参数为空
CAPTCHA_EXCEPTION
6
验证码检测异常
POLICY_ERROR
7
未同意隐私条款
CAPTCHA_TIMEOUT
8
验证码超时

JSONObject(验证码校验结束时回调返回业务参数)

字段名
值类型
说明
ret
Int
验证结果,0:验证成功。2:用户主动关闭验证码。
ticket
String
验证码返回的票据,当且仅当ret = 0 时 ticket 有值。

CaptchaAppId
String
验证码应用ID。
bizState
Any
自定义透传参数。
randstr
String
本次验证的随机串,后续票据校验时需传递该参数。
errorCode
Number
错误code ,详情请参见回调函数errorCode说明。
errorMessage
String
错误信息。


TencentCaptchaParam类(可选参数配置说明)

/**
* 自定义透传参数,业务可用该字段传递少量数据,该字段的内容会被带入 callback 回调的对象中。
*
* @param Object
* @return Builder
*/
Builder setBizState(Object);
/**
* true: 开启自适应深夜模式。
*
* @param boolean
* @return Builder
*/
Builder setEnableDarkMode(boolean);
/**
* "force": 开启强制深夜模式: 。
*
* @param String
* @return Builder
*/
Builder setEnableDarkMode(String);
/**
* false: 隐藏帮助按钮
*
* @param boolean
* @return Builder
*/
Builder setNeedFeedBack(boolean);
/**
* 自定义帮助链接: "url地址"
*
* @param String
* @return Builder
*/
Builder setNeedFeedBack(String);
/**
* 指定验证码提示文案的语言,优先级高于控制台配置。
* 支持传入值同 navigator.language 用户首选语言,大小写不敏感。
* 详情参见 https://www.tencentcloud.com/zh/document/product/1159/49680?lang=zh&pg=#userLanguage 。
*
* @param String
* @return Builder
*/
Builder setUserLanguage(String);
/**
* true: 开启适老化
* false:关闭适老化
*
* @param boolean
* @return Builder
*/
Builder setEnableAged(boolean);
/**
* 定义验证码展示方式。
* popup: (默认)弹出式,以浮层形式居中弹出展示验证码。
*
* @param String
* @return Builder
*/
Builder setType(String);
/**
* 是否在验证码加载过程中显示loading框。不指定该参数时,默认显示loading框。
* true: 显示loading框
* false: 不显示loading框
*
* @param boolean
* @return Builder
*/
Builder setLoading(boolean);
/**
* 设置CaptchaAppId 加密校验串,详情见 CaptchaAppid 加密校验能力接入指引
*
* @param String
* @return Builder
*/
Builder setAidEncrypted(String);
/**
* 回调验证码内部部分信息,详见【TencentCaptchaParam.OptionsCallback说明】。
*
* @param OptionsCallback
* @return Builder
*/
Builder setOptionsCallback(OptionsCallback);

/**
* 支持灵活设置对应key及value值
*
* @param String,对应key值
* @param Object,对应value值
* 如设置key为enableAutoCheck,设置value为true开启,将对安全的请求可自动完成勾选验证,无需用户操作。不设置默认为关闭。
* @return
*/
Builder setExtractParameter(String, Object);

/**
* 设置可访问的验证码接入host,如海外接入域名ca.turing.captcha.qcloud.com及www.tycaptcha.com二选一。
*
* @param String
* @return
*/
Builder setCaptchaPageHost(String);

/**
* 设置验证码毫秒级超时时间,最小值为10s。若不传,默认是60s。
* 极端网络情况下,验证码整体处理时间误差可能会达10s。可能出现无法加载验证码、安全类校验有缺失的情况。
*
* @param int
* @return
*/
Builder setCaptchaTimeoutMillis(int)
/**
* 【接口已停用,请统一用setCaptchaTimeoutMillis接口】
* 设置webview实际加载验证码的毫秒级超时,默认为60s。
* 验证码在加载前会做必要的网络连通性检查,该检查耗费时间视网络情况不同,最长耗时为5s。不包含在本方法设置的超时时间内。
*
* @param int
* @return
*/
Builder setWebviewCaptchaTimeoutMills(int);
/**
* 【接口已停用,请统一用setCaptchaTimeoutMillis接口】
* 设置验证码native时请求后台毫秒级超时,默认为60s。
*
* @param int
* @return
*/
Builder setNativeReqTimeoutMills(int);
/**
* 【接口已停用,请统一用setCaptchaTimeoutMillis接口】
* 设置验证码native时本地组包阶段(含降级处理)毫秒级超时。默认为10s。
*
* @param int
* @return
*/
Builder setNativePackTimeoutMills(int);
配置名
值类型
说明
enableAutoCheck
true
开启后,对安全的请求可自动完成勾选验证,无需用户操作,默认为关闭。
开启:{"enableAutoCheck":true}

TencentCaptchaParam.OptionsCallback说明

/**
* 1.optFuncName为ready时,
* data返回验证码加载完成的回调,回调参数为验证码实际的宽高(单位:px):
* {"sdkView": {
* "width": number,
* "height": number
* }}
* 该参数仅为查看验证码宽高使用,请勿使用此 参数直接设定宽高。
* 2.optFuncName为showFn时,data返回duration,渲染耗时 + sid 信息。
*
* @param optFuncName, String
* @param data, String
*/
void onCallback(String optFuncName, String data);结果回调,返回值

帮助和支持

本页内容是否解决了您的问题?

填写满意度调查问卷,共创更好文档体验。

文档反馈