This is documentation for the next SDK version. For up-to-date documentation, see the latest version (SDK 55).

Expo 本地认证

一个提供用于实现指纹 API（Android）或 Face ID 和 Touch ID（iOS）功能的库，通过面部或指纹扫描对用户进行身份验证。

Android

iOS

Included in Expo Go

GitHub

npm

更新日志

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

已知限制

iOS
iOS

Expo Go 不支持 iOS 的 FaceID 身份验证。你需要创建一个 development build 来测试 FaceID。

安装

Terminal

- npx expo install expo-local-authentication

If you are installing this in an existing React Native app, make sure to install expo in your project.

在 app config 中配置

如果你在项目中使用 config plugins（Continuous Native Generation (CNG)），你可以使用 expo-local-authentication 内置的 config plugin 进行配置。该插件允许你配置一些无法在运行时设置、且需要构建新的应用二进制文件后才会生效的属性。如果你的应用不使用 CNG，那么你需要手动配置该库。

Example app.json with config plugin

app.json

{
  "expo": {
    "plugins": [
      [
        "expo-local-authentication",
        {
          "faceIDPermission": "允许 $(PRODUCT_NAME) 使用 Face ID。"
        }
      ]
    ]
  }
}

Configurable properties

Name	Default	Description
`faceIDPermission`	`"允许 $(PRODUCT_NAME) 使用 Face ID"`	Only for: iOS 设置 `NSFaceIDUsageDescription` 权限消息的字符串。

Are you using this library in an existing React Native app?

如果你没有使用 Continuous Native Generation（CNG），或者你是手动使用原生 ios 项目，那么你需要向你的 ios/[app]/Info.plist 中添加 NSFaceIDUsageDescription 键：

Info.plist

<key>NSFaceIDUsageDescription</key>
<string>Allow $(PRODUCT_NAME) to use FaceID</string>

API

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

Methods

`LocalAuthentication.authenticateAsync(options)`

Android

iOS

Parameter	Type
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.

`LocalAuthentication.cancelAuthenticate()`

Android

Cancels authentication flow.

Returns:

Promise<void>

`LocalAuthentication.getEnrolledLevelAsync()`

Android

iOS

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()`

Android

iOS

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()`

Android

iOS

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()`

Android

iOS

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

`BiometricsSecurityLevel`

Android

Literal Type: string

Security level of the biometric authentication to allow.

Acceptable values are: 'weak' | 'strong'

`LocalAuthenticationError`

Android

iOS

Literal Type: string

One of the error values returned by the LocalAuthenticationResult object.

`LocalAuthenticationOptions`

Android

iOS

Property	Type	Description
biometricsSecurityLevel(optional)	`BiometricsSecurityLevel`	Only 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 customizing the default `Cancel` label shown.
disableDeviceFallback(optional)	`boolean`	After several failed attempts, the system falls back 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)	`string`	Only 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.
promptDescription(optional)	`string`	Only for: Android A description displayed in the middle of the authentication prompt.
promptMessage(optional)	`string`	A message that is shown alongside the TouchID or FaceID prompt.
promptSubtitle(optional)	`string`	Only for: Android A subtitle displayed below the prompt message in the authentication prompt.
requireConfirmation(optional)	`boolean`	Only 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`

Android

iOS

Type: object shaped as below:

Property	Type	Description
success	`true`	-

Or object shaped as below:

Property	Type	Description
error	`LocalAuthenticationError`	-
success	`false`	-
warning(optional)	`string`	-

Enums

`AuthenticationType`

Android

iOS

`FINGERPRINT`

AuthenticationType.FINGERPRINT ＝ 1

Indicates fingerprint support.

`FACIAL_RECOGNITION`

AuthenticationType.FACIAL_RECOGNITION ＝ 2

Indicates facial recognition support.

`IRIS`

Android

AuthenticationType.IRIS ＝ 3

Indicates iris recognition support.

`SecurityLevel`

Android

iOS

`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.

权限

Android

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

Android Permission	Description
`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

此库使用以下用途说明键：

Info.plist Key	Description
`NSFaceIDUsageDescription`	A message that tells the user why the app is requesting the ability to authenticate with Face ID.

Expo 本地认证

已知限制

iOS iOS

安装

在 app config 中配置

Example app.json with config plugin

Configurable properties

API

Methods

LocalAuthentication.authenticateAsync(options)

LocalAuthentication.cancelAuthenticate()

LocalAuthentication.getEnrolledLevelAsync()

LocalAuthentication.hasHardwareAsync()

LocalAuthentication.isEnrolledAsync()

LocalAuthentication.supportedAuthenticationTypesAsync()

Types

BiometricsSecurityLevel

LocalAuthenticationError

LocalAuthenticationOptions

LocalAuthenticationResult

Enums

AuthenticationType

FINGERPRINT

FACIAL_RECOGNITION

IRIS

SecurityLevel

NONE

SECRET

BIOMETRIC_WEAK

BIOMETRIC_STRONG

权限

Android

iOS

iOS
iOS

`LocalAuthentication.authenticateAsync(options)`

`LocalAuthentication.cancelAuthenticate()`

`LocalAuthentication.getEnrolledLevelAsync()`

`LocalAuthentication.hasHardwareAsync()`

`LocalAuthentication.isEnrolledAsync()`

`LocalAuthentication.supportedAuthenticationTypesAsync()`

`BiometricsSecurityLevel`

`LocalAuthenticationError`

`LocalAuthenticationOptions`

`LocalAuthenticationResult`

`AuthenticationType`

`FINGERPRINT`

`FACIAL_RECOGNITION`

`IRIS`

`SecurityLevel`

`NONE`

`SECRET`

`BIOMETRIC_WEAK`

`BIOMETRIC_STRONG`