fingerprint

Fingerprint模块管理指纹识别。

Android平台6.0及以上系统支持，仅适配Google官方指纹识别的标准接口的设备。

方法：

对象：

回调方法：

权限：

5+功能模块（permissions）

  2. {
  3. // ...
  4. "permissions":{
  5.     // ...
  6.     "Fingerprint": {
  7.         "description": "指纹识别"
  8.     }
  9. }
  10. }
  11.

isSupport

当前设备环境是否支持指纹识别

  2. boolean plus.fingerprint.isSupport();
  3.

说明：

目前还有很多设备没有指纹识别模块，需要调用此方法判断是否可使用指纹识别功能。

参数：

无

返回值：

Boolean: 设备支持指纹识别则返回true，否则返回false。

示例：

  2. <!DOCTYPE html>
  3. <html>
  4.     <head>
  5.     <meta charset="utf-8">
  6.     <meta name="viewport" content="width=device-width,initial-scale=1.0,maximum-scale=1.0,user-scalable=no"/>
  7.     <title>Fingerprint Example</title>
  8.     <script type="text/javascript">
  9. // H5 plus事件处理
  10. function plusReady(){
  11.     // 判断设备是否支持指纹识别
  12.     if(plus.fingerprint) {
  13.         document.getElementById('result').innerText = plus.fingerprint.isSupport()?'支持':'不支持';
  14.     }else {
  15.         console.log("请更新版本");
  16.     }
  17. }
  18. document.addEventListener('plusready', plusReady, false);
  19.     </script>
  20.     </head>
  21.     <body >
  22.         当前设备环境是否支持指纹识别：
  23.         <br/>
  24.         <p id="result">...</p>
  25.     </body>
  26. </html>
  27.

uni-app使用plus注意事项

isKeyguardSecure

当前设备是否设置密码锁屏


boolean plus.fingerprint.isKeyguardSecure();

说明：

如果设备没有设置密码锁屏，则无法使用指纹识别功能，建议调用指纹识别前先使用此接口检查。调用plus.fingerprint.authenticate会返回失败。

参数：

无

返回值：

Boolean: 设备已设置密码锁屏则返回true，否则返回false。

平台支持：

  • Android(支持): 要求设置密码锁屏才可以使用指纹识别，如果没有设置密码锁屏应该提示用户进行设置。
  • iOS(不支持): 不支持此功能，返回true。

示例：


<!DOCTYPE html>
<html>
    <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width,initial-scale=1.0,maximum-scale=1.0,user-scalable=no"/>
    <title>Fingerprint Example</title>
    <script type="text/javascript">
// H5 plus事件处理
function plusReady(){
    // 判断设备是否设置密码锁屏
    if(plus.fingerprint) {
        document.getElementById('result').innerText = plus.fingerprint.isKeyguardSecure()?'是':'否';
    }else {
        console.log("请更新版本");
    }
}
document.addEventListener('plusready', plusReady, false);
    </script>
    </head>
    <body >
        当前设备是否设置密码锁屏：
        <br/>
        <p id="result">...</p>
    </body>
</html>

uni-app使用plus注意事项

isEnrolledFingerprints

当前设备是否已经录入指纹


boolean plus.fingerprint.isEnrolledFingerprints();

说明：

如果设备没有录入指纹，则无法使用指纹识别功能，建议调用指纹识别前先使用此接口检查。调用plus.fingerprint.authenticate会返回失败。

参数：

无

返回值：

Boolean: 设备已经录入指纹则返回true，否则返回false。

示例：


<!DOCTYPE html>
<html>
    <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width,initial-scale=1.0,maximum-scale=1.0,user-scalable=no"/>
    <title>Fingerprint Example</title>
    <script type="text/javascript">
// H5 plus事件处理
function plusReady(){
    // 判断设备是否已经录入指纹
    if(plus.fingerprint) {
        document.getElementById('result').innerText = plus.fingerprint.isEnrolledFingerprints()?'是':'否';
    }else {
        console.log("请更新版本");
    }
}
document.addEventListener('plusready', plusReady, false);
    </script>
    </head>
    <body >
        当前设备是否已经录入指纹：
        <br/>
        <p id="result">...</p>
    </body>
</html>

uni-app使用plus注意事项

authenticate

指纹识别认证


void plus.fingerprint.authenticate(successCB, errorCB, options);

说明：

用户可以开始输入指纹进行识别，如果认证成功则触发successCB回调，识别失败则触发errorCB回调返回错误信息。

参数：

  • successCB: (FingerprintSuccessCallback)必选 识别认证成功回调指纹识别操作认证成功时调用。
  • errorCB: (FingerprintErrorCallback)必选 指纹识别操作认证失败时调用，每次指纹识别错误都会触发一次错误回调。
  • options: (AuthenticateOptions)可选 识别认证参数用于设置指纹识别界面显示的提示信息等。

返回值：

void: 无

平台支持：

  • Android(支持): 指纹识别过程中不会弹出任何界面，需要开发者根据业务需求弹出提示信息。
  • iOS(支持): 指纹识别过程中会弹出系统界面。

示例：


<!DOCTYPE html>
<html>
    <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width,initial-scale=1.0,maximum-scale=1.0,user-scalable=no"/>
    <title>Fingerprint Example</title>
    <script type="text/javascript">
// H5 plus事件处理
function plusReady(){
    var result = document.getElementById('result');
    // 检查是否支持指纹识别
    if(plus.fingerprint) {
        if(!plus.fingerprint.isSupport()) {
            result.innerText = '此设备不支持指纹识别';
            return;
        }
        if(!plus.fingerprint.isKeyguardSecure()) {
            result.innerText = '此设备未设置密码锁屏，无法使用指纹识别';
            return;
        }
        if(!plus.fingerprint.isEnrolledFingerprints()) {
            result.innerText = '此设备未录入指纹，请到设置中开启';
            return;
        }
        result.innerText = '此设备支持指纹识别';
    }else {
        result.innerText = '当前环境不支持指纹识别API，请更新到最新版本';
    }
}
document.addEventListener('plusready', plusReady, false);

// 指纹识别认证 
function fingerpring() {
    var waiting = null;
    plus.fingerprint.authenticate(function(){
        plus.nativeUI.closeWaiting();//兼容Android平台关闭等待框
        alert('指纹识别成功');
    }, function(e){
        switch(e.code) {
        case e.AUTHENTICATE_MISMATCH:
        plus.nativeUI.toast('指纹匹配失败，请重新输入');
        break;
        case e.AUTHENTICATE_OVERLIMIT:
        plus.nativeUI.closeWaiting();//兼容Android平台关闭等待框
        plus.nativeUI.alert('指纹识别失败次数超出限制，请使用其它方式进行认证');
        break;
        default:
        plus.nativeUI.closeWaiting();//兼容Android平台关闭等待框
        plus.nativeUI.alert('指纹识别失败('+e.code+')，请重试');
        break;
        }
    });
    // Android平台弹出等待提示框 
    if('Android'==plus.os.name) {
        plus.nativeUI.showWaiting('指纹识别中...');
    }
}
    </script>
    </head>
    <body >
        指纹识别认证：
        <br/>
        <p id="result">...</p>
        <br/>
        <button onclick="fingerpring()">指纹识别</button>
    </body>
</html>

uni-app使用plus注意事项

cancel

取消指纹识别认证


void plus.fingerprint.cancel();

说明：

取消当前正在处理的指纹识别认证操作。如果当前没有进行指纹识别则不进行任何操作；如果当前正在进行指纹识别则触发错误回调（错误码为“CANCEL”）。

参数：

无

返回值：

void: 无

示例：


<!DOCTYPE html>
<html>
    <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width,initial-scale=1.0,maximum-scale=1.0,user-scalable=no"/>
    <title>Fingerprint Example</title>
    <script type="text/javascript">
// H5 plus事件处理
function plusReady(){
    // 自动调用指纹识别
    plus.fingerprint.authenticate(function(){
        plus.nativeUI.toast('指纹识别成功');
    }, function(e){
        plus.nativeUI.alert('指纹识别失败('+e.code+')');
    });
    // iOS平台指纹识别提示框会阻塞界面操作，定时调用
    if('iOS'==plus.os.name) {
        setTimeout(cancelFingerpring, 10000);
    }
}
document.addEventListener('plusready', plusReady, false);

// 取消指纹识别
function cancelFingerpring() {
    plus.fingerprint.cancel();
}
    </script>
    </head>
    <body >
        取消指纹识别认证
        <br/>
        <button onclick="cancelFingerpring()">取消识别</button>
        <br/>
        注意：iOS平台10秒后自动取消
    </body>
</html>

uni-app使用plus注意事项

AuthenticateOptions

JSON对象，指纹识别认证参数


interface AuthenticateOptions {
    readonly attribute String message;
}

说明：

用于设置指纹识别认证界面显示的提示信息等。

属性：

  • message: (String类型)在指纹识别过程中显示在界面上的提示信息如果指纹识别认证过程中不显示提示框，则不显示此信息。

平台支持

  • Android - (不支持): 指纹识别认证过程中不显示提示框，需要开发者自定义显示。
  • iOS - (支持): 指纹识别认证过程中显示系统提示框，在提示框中显示此信息（默认显示信息为空字符串）。

<!DOCTYPE html>
<html>
    <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width,initial-scale=1.0,maximum-scale=1.0,user-scalable=no"/>
    <title>Fingerprint Example</title>
    <script type="text/javascript">
// H5 plus事件处理
function plusReady(){
    var waiting = null;
    // 自动调用指纹识别
    plus.fingerprint.authenticate(function(){
        waiting&&(waiting.onclose=null);
        plus.nativeUI.closeWaiting();
        plus.nativeUI.alert('指纹识别成功');
    }, function(e){
        if(e.AUTHENTICATE_MISMATCH == e.code){
            plus.nativeUI.toast('指纹匹配失败，请重新输入');
            return;
        }
        waiting&&(waiting.onclose=null);
        plus.nativeUI.closeWaiting();
        plus.nativeUI.alert('指纹识别失败('+e.code+')');
    },{
        message:'通过Home键验证已有手机指纹'
    });
    // Android平台使用自定义等待框显示 
    if("Android"==plus.os.name){
        waiting = plus.nativeUI.showWaiting('验证已有手机指纹',{width:'196px',height:'196px',padding:'16px',loading:{height:'96px',icon:'fp.png'},background:'rgba(0,0,0,0.3)'});
        waiting.onclose = function(){
            waiting = null;
            plus.fingerprint.cancel();
        }
    }
}
document.addEventListener('plusready', plusReady, false);
    </script>
    </head>
    <body >
        指纹识别认证
    </body>
</html>

FingerprintError

JSON对象，指纹识别错误信息


interface FingerprintError {
    const Number UNSUPPORT = 1;
    const Number KEYGUARD_INSECURE = 2;
    const Number FINGERPRINT_UNENROLLED = 3;
    const Number AUTHENTICATE_MISMATCH = 4;
    const Number AUTHENTICATE_OVERLIMIT = 5;
    const Number CANCEL = 6;
    const Number UNKNOWN_ERROR = 7;
    readonly attribute Number code;
    readonly attribute String message;
}

常量：

  • UNSUPPORT: (Number类型)不支持指纹识别当前设备不支持指纹识别功能时返回此错误，错误代码常量值为1。

  • KEYGUARDINSECURE: (Number类型)_设备未设置密码锁屏当前设备为设置密码锁屏导致无法使用指纹识别功能时返回此错误，错误代码常量值为2。

  • FINGERPRINTUNENROLLED: (Number类型)_未录入指纹识别当前设备未录入指纹导致无法使用指纹识别功能时返回此错误，错误代码常量值为3。

  • AUTHENTICATEMISMATCH: (Number类型)_指纹识别不匹配用户指纹识别认证不通过时返回此错误，错误代码常量值为4。用户每次尝试指纹识别认证未通过都会触发此错误，此时还可以继续识别认证。

  • AUTHENTICATEOVERLIMIT: (Number类型)_指纹识别次数超过限制用户多次指纹识别认证不通过时返回此错误，错误代码常量值为5。通常出现此错误后系统会锁定一段时间禁止使用指纹识别，如果再次调用指纹识别认证会立即返回此错误，因此出现此错误时应该提示用户使用其它方式进行认证。

  • CANCEL: (Number类型)取消指纹识别用户取消指纹识别认证时返回此错误，错误代码常量值为6。

  • UNKNOWNERROR: (Number类型)_未知错误其它未知错误，错误代码常量值为7。

属性：

  • code: (Number类型)错误代码取值范围为FingerprintError对象的错误常量值。

  • message: (String类型)错误描述信息详细错误描述信息。

FingerprintSuccessCallback

指纹识别认证成功回调函数


void onSuccess() {
    // Authenticate success code.
}

参数：

无

返回值：

void: 无

示例：


<!DOCTYPE html>
<html>
    <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width,initial-scale=1.0,maximum-scale=1.0,user-scalable=no"/>
    <title>Fingerprint Example</title>
    <script type="text/javascript">
// H5 plus事件处理
function plusReady(){
    // 自动调用指纹识别
    plus.fingerprint.authenticate(function(){
        plus.nativeUI.alert('指纹识别成功');
    }, function(e){
        console.log('指纹识别失败('+e.code+')');
    });
}
document.addEventListener('plusready', plusReady, false);
    </script>
    </head>
    <body >
        指纹识别认证
    </body>
</html>

uni-app使用plus注意事项

FingerprintErrorCallback

指纹识别认证失败的回调函数


function void onError(FingerprintError error) {
    // Handle error
    var code = error.code; // 错误编码
    var message = error.message; // 错误描述信息
}

参数：

  • error: (FingerprintError)必选 获取加速度操作的错误信息可通过error.code（Number类型）获取错误编码；可通过error.message（String类型）获取错误描述信息。

返回值：

void: 无

示例：


<!DOCTYPE html>
<html>
    <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width,initial-scale=1.0,maximum-scale=1.0,user-scalable=no"/>
    <title>Fingerprint Example</title>
    <script type="text/javascript">
// H5 plus事件处理
function plusReady(){
    // 自动调用指纹识别
    plus.fingerprint.authenticate(function(){
        console.log('指纹识别成功');
    }, function(e){
        switch(e.code) {
        case e.AUTHENTICATE_MISMATCH:
        plus.nativeUI.alert('指纹匹配失败，请重新输入');
        break;
        case e.AUTHENTICATE_OVERLIMIT:
        plus.nativeUI.alert('指纹识别失败次数超出限制，请使用其它方式进行认证');
        break;
        default:
        plus.nativeUI.alert('指纹识别失败('+e.code+')，请重试');
        break;
        }
    });
}
document.addEventListener('plusready', plusReady, false);
    </script>
    </head>
    <body >
        指纹识别认证
    </body>
</html>

uni-app使用plus注意事项