首页指南参考教程

Expo LocalAuthentication iconExpo LocalAuthentication

GitHub

npm

一个库，提供用于实现 Fingerprint API (Android) 或 FaceID 和 TouchID (iOS) 的功能，以通过面部或指纹扫描对用户进行身份验证。

Android
iOS

expo-local-authentication 允许你使用生物识别提示 (Android) 或 FaceID 和 TouchID (iOS) 通过指纹或面部扫描来验证用户身份。

¥expo-local-authentication allows you to use the Biometric Prompt (Android) or FaceID and TouchID (iOS) to authenticate the user with a fingerprint or face scan.

安装

¥Installation

Terminal
- npx expo install expo-local-authentication

If you're installing this in a bare React Native app, you should also follow these additional installation instructions.

app.json/app.config.js 中的配置

¥Configuration in app.json/app.config.js

如果你在项目中使用配置插件（EAS 构建 或 npx expo run:[android|ios]），则可以使用其内置的 配置插件 配置 expo-local-authentication。该插件允许你配置无法在运行时设置的各种属性，并且需要构建新的应用二进制文件才能生效。

¥You can configure expo-local-authentication using its built-in config plugin if you use config plugins in your project (EAS Build or npx expo run:[android|ios]). The plugin allows you to configure various properties that cannot be set at runtime and require building a new app binary to take effect.

Example app.json with config plugin

app.json
{
  "expo": {
    "plugins": [
      [
        "expo-local-authentication",
        {
          "faceIDPermission": "Allow $(PRODUCT_NAME) to use Face ID."
        }
      ]
    ]
  }
}

Configurable properties

NameDefaultDescription
faceIDPermission"Allow $(PRODUCT_NAME) to use Face ID"Only for: 
iOS

A string to set the NSFaceIDUsageDescription permission message.

Are you using this library in a bare React Native app?

了解如何在 expo-local-authentication 存储库中的安装说明 文件中配置原生项目。

¥Learn how to configure the native projects in the installation instructions in the expo-local-authentication repository.

API

import * as LocalAuthentication from 'expo-local-authentication';

Methods

LocalAuthentication.authenticateAsync(options)

NameTypeDescription
options
(optional)		LocalAuthenticationOptions-

Attempts to authenticate via Fingerprint/TouchID (or FaceID if available on the device).

Note: Apple requires apps which use FaceID to provide a description of why they use this API. If you try to use FaceID on an iPhone with FaceID without providing infoPlist.NSFaceIDUsageDescription in app.json, the module will authenticate using device passcode. For more information about usage descriptions on iOS, see permissions guide.

Returns

  • Promise<LocalAuthenticationResult>

Returns a promise which fulfils with LocalAuthenticationResult.

Only for: 
Android

LocalAuthentication.cancelAuthenticate()

Cancels authentication flow.

Returns

  • Promise<void>

LocalAuthentication.getEnrolledLevelAsync()

Determine what kind of authentication is enrolled on the device.

Returns

  • Promise<SecurityLevel>

Returns a promise which fulfils with SecurityLevel.

Note: On Android devices prior to M, SECRET can be returned if only the SIM lock has been enrolled, which is not the method that authenticateAsync prompts.

LocalAuthentication.hasHardwareAsync()

Determine whether a face or fingerprint scanner is available on the device.

Returns

  • Promise<boolean>

Returns a promise which fulfils with a boolean value indicating whether a face or fingerprint scanner is available on this device.

LocalAuthentication.isEnrolledAsync()

Determine whether the device has saved fingerprints or facial data to use for authentication.

Returns

  • Promise<boolean>

Returns a promise which fulfils to boolean value indicating whether the device has saved fingerprints or facial data for authentication.

LocalAuthentication.supportedAuthenticationTypesAsync()

Determine what kinds of authentications are available on the device.

Returns

  • Promise<AuthenticationType[]>

Returns a promise which fulfils to an array containing AuthenticationTypes.

Devices can support multiple authentication methods- i.e. [1,2] means the device supports both fingerprint and facial recognition. If none are supported, this method returns an empty array.

Types

Only for: 
Android

BiometricsSecurityLevel

Literal Type: string

Security level of the biometric authentication to allow.

Acceptable values are: 'weak' | 'strong'

LocalAuthenticationOptions

NameTypeDescription
biometricsSecurityLevel
(optional)		BiometricsSecurityLevelOnly for: 
Android

Sets the security class of biometric authentication to allow. strong allows only Android Class 3 biometrics. For example, a fingerprint or a 3D face scan. weak allows both Android Class 3 and Class 2 biometrics. Class 2 biometrics are less secure than Class 3. For example, a camera-based face unlock.

Default: 'weak'
cancelLabel
(optional)		string

Allows to customize the default Cancel label shown.

disableDeviceFallback
(optional)		boolean

After several failed attempts the system will fallback to the device passcode. This setting allows you to disable this option and instead handle the fallback yourself. This can be preferable in certain custom authentication workflows. This behaviour maps to using the iOS LAPolicyDeviceOwnerAuthenticationWithBiometrics policy rather than the LAPolicyDeviceOwnerAuthentication policy. Defaults to false.

fallbackLabel
(optional)		stringOnly for: 
iOS

Allows to customize the default Use Passcode label shown after several failed authentication attempts. Setting this option to an empty string disables this button from showing in the prompt.

promptMessage
(optional)		string

A message that is shown alongside the TouchID or FaceID prompt.

requireConfirmation
(optional)		booleanOnly for: 
Android

Sets a hint to the system for whether to require user confirmation after authentication. This may be ignored by the system if the user has disabled implicit authentication in Settings or if it does not apply to a particular biometric modality. Defaults to true.

LocalAuthenticationResult

object shaped as below:


NameTypeDescription
successtrue-

NameTypeDescription
errorstring-
successfalse-
warning
(optional)		string-

Enums

AuthenticationType

AuthenticationType Values

FINGERPRINT

AuthenticationType.FINGERPRINT ＝ 1

Indicates fingerprint support.

FACIAL_RECOGNITION

AuthenticationType.FACIAL_RECOGNITION ＝ 2

Indicates facial recognition support.

Only for: 
Android

IRIS

AuthenticationType.IRIS ＝ 3

Indicates iris recognition support.

SecurityLevel

SecurityLevel Values

NONE

SecurityLevel.NONE ＝ 0

Indicates no enrolled authentication.

SECRET

SecurityLevel.SECRET ＝ 1

Indicates non-biometric authentication (e.g. PIN, Pattern).

BIOMETRIC_WEAK

SecurityLevel.BIOMETRIC_WEAK ＝ 2

Indicates weak biometric authentication. For example, a 2D image-based face unlock.

There are currently no weak biometric authentication options on iOS.

BIOMETRIC_STRONG

SecurityLevel.BIOMETRIC_STRONG ＝ 3

Indicates strong biometric authentication. For example, a fingerprint scan or 3D face unlock.

权限

¥Permissions

安卓

¥Android

通过该库的 AndroidManifest.xml 自动添加以下权限：

¥The following permissions are added automatically through this library's AndroidManifest.xml:

Android PermissionDescription

USE_BIOMETRIC

Allows an app to use device supported biometric modalities.

USE_FINGERPRINT

This constant was deprecated in API level 28. Applications should request USE_BIOMETRIC instead

iOS 系统

¥iOS

该库使用以下用法描述键：

¥The following usage description keys are used by this library:

Info.plist KeyDescription

NSFaceIDUsageDescription

A message that tells the user why the app is requesting the ability to authenticate with Face ID.
Expo 中文网 - 粤ICP备13048890号