Client-side integration

# Client-side integration

Insert the javascript below to the head tag of your key page, such as Sign-in, Sign-up, Find-password, and other pages that require a captcha challenge:

<script type="text/javascript">
  (function() {
     _fmOpt = {
        partner: 'pc_xxx',
        appName: 'an_xxx',
        display: 'bind', // bind type
        container: '#captcha', // target dom for the trigger button
        initialTime: new Date().getTime(), 
    };

    var fm = document.createElement('script'); 
    fm.type = 'text/javascript';
    fm.src = 'Base URL' + '?t=' + (new Date().getTime()/600000).toFixed(0);
    var s = document.getElementsByTagName('script')[0];
    s.parentNode.insertBefore(fm, s);
 })();
</script>

Base URL

Region	Base URL
China	https://static.tongdun.net/captcha/main/tdc.js
North America	https://static.tongdun.net/us/captcha/main/tdc.js
Singapore	https://static.tongdun.net/sg/captcha/main/tdc.js
Germany	https://static.tongdun.net/fra/captcha/main/tdc.js

Note: If you have embedded the fingerprint of TD, please remove the relevant code first.

# Configurations

You can make your configuration by the _fmOpt object of the integration above. The common configuration of the parameters have been given in the sample code, but you can also make further configuration following the parameter descriptions below.

# Action Mode

Action mode	Description
bind type	the trigger event will be bound to the button dom that you specified, such as sign-in, sign-up, and other buttons.
trigger type	there will render a button named `Click to verify` automatically

# Parameters List

Parameter	Type	Required	Description
partner	String	Yes	partner code, assigned by TD
appName	String	Yes	application id, assigned by TD
display	String	Yes	display mode, optional value: popup/float/custom/bind. detail explanation: popup: the captcha dialog will be displayed in the middle of the screen and filled with a mask outside it. Users can close the captcha dialog by clicking the mask. float: the captcha dialog will be rendered above the specified button. custom: the captcha dialog will be rendered in the area dom that you specified. bind: the captcha dialog will be displayed in the middle of the screen also, corresponding to the bind action mode.
container	String	Yes	dom selector. For bind action mode, it is used to specify the dom of the button which will trigger the captcha event. For trigger action mode, it is used to specify the dom where the button will render automatically.
area	String	No	dom selector. Only for custom display mode. It is used to specify where the captcha dialog will render.
width	String	No	the width of the button that is rendered automatically for the trigger action mode. Default: 300px, min: 200px
height	String	No	the height of the button that is rendered automatically for the trigger action mode. Default: 40px, min: 30px
lang	String	No	Language configuration, optional value:zh-cn(Chinese simplified),zh-han(Chinese Traditional),en(English), ja(Japanese),ko(Korean), ba(Malay), tha(Thai), idn(Indonesian), rus(Russian). Default: zh-cn(Chinese simplified)
bindSucNoFed	Boolean	No	Only for bind display mode. If false, it will give a successful `toast` after verifying successfully. if true, no `toast` will show. Default: false.
env	Number	No	0: test environment, 1: production environment. Default: 1
closeIcon	Number	No	0: show close icon, 1: hide close icon. Default: 0
closeMask	Number	No	when the user triggers a click event on the mask outside the captcha dialog, 0: hide the captcha dialog, 1: cannot hide the captcha dialog. Default: 0
mfaId	String	No	If you have connected to the MFA product (the parameter can be ignored if the MFA is not connected), please set the `mfa_id` which is obtained from the MFA process to the configuration parameter `_fmOpt`. Example: _fmOpt.mfaId = res.data.mfa_id;

# Methods

The following callback methods can be defined on the _fmOpt object as needed:

beforeValidate: if you have defined this method, it will be invoked before triggering the captcha. If the method returns true, the captcha logic will continue. false the captcha logic will stop. For example:

// The following code makes a simple judgment: when the username input box or password input box gets null values, it will be returned false, and the captcha logic will not be triggered in this case.
_fmOpt.beforeValidate = function() {
    if ($('#username').val() === '' || $('#password').val() === '') {
        alert('username or password error.');
        return false;
    }
    return true;
}

onReady: the captcha logic is ready at this time. If you have a loading before triggering the captcha event, you can remove it at this point.
onClose: It will be invoked after the captcha dialog is closed.
onSuccess(validateToken): It will be invoked after the verification succeed. For example:

_fmOpt.onSuccess = function (validateToken) {
    // demo, an ajax request
    ajax('/submit', {
        account: '***',
        password: '***',
        token: validateToken, // after verifying successfully, you need to invoke the API interface on your backend service to recheck the verification.
        blackBox: _fmOpt.getinfo ? _fmOpt.getinfo() : '' // get the blackbox
    })
};

onFail(msg): It will be invoked after the verification failed, callback parameters description：

msg(String)	description
opFail	verification failed
op2much	verification too much
noNetwork	timeout or no network
limit	request limit （503）

The following methods can be invoked as needed:

triggerCaptcha: If you want to trigger the captcha to challenge by yourself:

_fmOpt.triggerCaptcha() // It is used to trigger captcha initiatively

reset： reset the captcha to the initial state. This usually occurs when the user has passed the verification of the captcha, but the username or password is incorrect. In this case, you need to trigger the captcha again. For example:

// demo, ajax request
ajax('/submit', {
    username: '***',
    password: '***',
    token: validateToken,
    blackBox: _fmOpt.getinfo ? _fmOpt.getinfo() : '' // get the blackbox
}, function(success) {
    if (!success) {  
        // service checked failed
        // reset the captcha, the user needs to trigger the captcha again
        _fmOpt.reset(); 
    }
})

newCaptcha: When a page needs to display multiple captchas, you can call this method to initialize a new captcha object. At this time, you need to pass in the specific parameters of the new verification. For example:

var secondCaptchaObj = {
    display: 'popup',
    container: '#area',
};

var secondCaptcha = _fmOpt.newCaptcha(secondCaptchaObj);
secondCaptcha.onSuccess = function (validateToken) {
    console.log('second captcha verification succeed: ' + validateToken);
    // todo
};

# FAQ

Q: CSS style problem (such as a captcha image broken, layout disordered...)?

/** If the global style is set with important, the priority level is higher than the captcha style, which will cause the style to be overwritten. For example(not recommended) **/
img{
  width:100%;!important;
}

Q: For the bind display mode, no response with clicking the trigger button?

1. Please confirm whether the JS-SDK of TD Captcha has loaded correctly.
2. Please confirm Whether the bound button element exists when the JS-SDK is initialized. If the element is not rendered, the trigger event will not be bound to the button.

Q: The callback method was not invoked after verifying succeed or failed？

onSuccess, onFail, and other callback methods need to be bound to the _fmOpt object when the JS-SDK is initialized, otherwise, the callback method cannot be found and cannot be triggered

Q: The callback method is not invoked for the captcha object created by the _fmOpt.newCaptcha method ?

var secondCaptcha = _fmOpt.newCaptcha(secondCaptchaObj);
secondCaptcha.onSuccess = function(validateToken) {...}
// the callback methods should be bound to the new secondCaptcha, and cannot be bound to _fmOpt object

← iOS WeChat →