The verification service uses the fingerprint to detect whether it is a risky device. This document describes how to integrate the fingerprint SDK and the verification SDK.

Backend Configuration

In the ByteDance Developer Platform, Development Management - Development Settings - Server Domain

Add request legal domain name

https://fp.tongdun.net
https://sphinx.tongdun.net
https://static.tongdun.net

Add downloadFile legal domain

https://sphinx.tongdun.net
https://static.tongdun.net

Mini program code integration

1. Get & Add SDK

Get the latest fingerprint SDK and captcha SDK from the operator of TD.

Add the fingerprint SDK to a appropriate directory of the mini program, add the tdcaptcha component folder in the captcha SDK to the mini program components directory.

2. Get the blackbox

The fingerprint uses the canvas fingerprint technology. Due to the current limitations of the mini program, it is not possible to dynamically create DOM nodes through JS, so you need to add it manually during integration. For example, add the following code to the end of the pages/index/index.ttml page.

<view>
    <canvas canvas-id='tdcanvas' style="visibility: hidden;position: fixed;z-index: -999;left: 9999px;"></canvas>
</view>

Import the SDK at the top of the pages/index/index.js file.

import FMAgent from '... /... /fmsdk/fm-xxx-es.saas.js'

Then get the blackbox in the onLoad method, the blackbox only needs to get once:

onLoad: function() {
	var that = this;
        // partnerCode - partner identifier, assigned by the same shield, appName - application identifier, assigned by the same shield
	var fmagent = new FMAgent({{partnerCode:"", appName:"", env: "PRODUCTION"}});
        fmagent.getInfo({
          page: that, 
          // If you have the unionid, please pass the encrypted unionid
          unionid: '', 
          success: function (res) {
             // get blackbox success callback, res is the blackbox string
             // setData can be saved to the page and passed to the CAPTCHA API
             that.setData({blackbox: res});
          },
         }
        })
   
}

fmagent.getInfo API parameter description

parameters	type	Required	Description	Example
mode	String	Yes	integrated mode	'plugin'
page	Object	Yes	current page object or a component object	that
unionid	String	No	the encrypted user unionid; you can choose any encryption algorithm, please ensure that the encrypted one-to-one correspondence relationship, we recommend using MD5 or SHA256; if the value is null, please send an empty String	ef54040ea***58fe66157
timeout	Number	No	API timeout (2500ms by default)	6000
noClipboard	Boolean	No	if don't collect the clipboard data (some mobile phones will give a reminder with "get the data of your clipboard").True by default.	true
success	function	yes	The callback function, the parameter of the function is the blackbox.	function(res){// res is the blackbox}

3. Add reference components

Add the tdcaptcha component to the .json file that requires the captcha challenge

{
  "usingComponents": {
    "td-captcha": "/components/tdcaptcha/captcha/index"
  }
}

4. Add tdcaptcha dom element

Add the tdcaptcha component node to the .ttml file that requires the captcha challenge

<td-captcha tt:ref="captchaRef" id="tdCaptcha"></td-captcha>

5. Trigger the captcha

Trigger the captcha to verify in the .js file of the page that requires the captcha challenge

  onReady() {
    // Get an instance of the captcha plug-in. Below id-selector should match the id of the node in the .ttml file
    this.selectComponent("#tdCaptcha", res => {
        this.tdcaptcha = res;
    })
   
  },
  
  // captchaRef is consistent with tt:ref in ttml
  // Get an instance of the captcha plug-in (supported in 2.23)
  captchaRef(ref) {
    this.tdcaptcha = ref;
  },
  // Invoke the API and trigger the captcha to pop up
  td.captcha.triggerCaptcha({
      partnerCode: '', // Partner identifier, assigned by TD
      appName: '', // Application identifier, assigned by TD
      env: 1, // 1-production, 0-test environment
      blackbox: this.data.blackbox || '',  // the blackbox obtained from the fingerprint
      onSuccess: this.onSuccess, // success callback from the verification
      onFail: this.onFail, // failure callback from the verification
   });
  },
  
  onSuccess: function(validateToken) {
    // The verification is successful
    // Pass the validateToken to the server for secondary verification
  },

  onFail: function(msg) {
    // todo
  },

The Captcha API Parameter Description

Parameter	Type	Description	Required
partnerCode	String	partner identifier, assigned by TD	Yes
appName	String	application identifier, assigned by TD	Yes
env	Number	1: production environment; 0: test environment	No
blackbox	String	the blackbox obtained from the fingerprint	No
maskClose	Number	1: the captcha dialog can be closed by clicking the mask layer; 0: can not	No
onSuccess	Function	Callback function after verifying success, the callback parameter isvalidateToken which you need to pass to the backend service to recheck.	Yes
onFail	Function	Callback function after verifying failed. The captcha will refresh after verifying failure, and the callback parameter will return 'opFail', which generally does not need further processing. For other errors, such as too many attempts to, request timeout, we suggest giving a toast to the user.	No
onClose	Function	Callback function after the captcha closed	No
mfaId	String	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	No