Flutter无界面本地认证插件 flutter_local_auth_invisible 的使用

flutter_local_auth_invisible 是官方 local_auth 插件的一个分支，提供了在设备上进行本地用户身份验证的功能。它支持 iOS 上的生物识别（Touch ID 或锁屏密码）和 Android 6.0 及以上版本中的指纹 API。

功能特点

• 支持 Face ID 和指纹识别。
• 在 Android 上可以自定义 UI，因为它会抑制标准的系统级指纹认证对话框。
• 提供默认的错误提示对话框，也可以关闭这些对话框并自行处理错误。

使用示例

导入包

首先，在 Dart 文件中导入该插件：

import 'package:flutter_local_auth_invisible/flutter_local_auth_invisible.dart';

检查设备是否支持生物识别

可以通过调用 canCheckBiometrics 方法来检查设备是否支持生物识别：

bool canCheckBiometrics = await LocalAuthentication.canCheckBiometrics;

获取已注册的生物识别类型

通过调用 getAvailableBiometrics 方法获取当前设备上已注册的生物识别类型：

List<BiometricType> availableBiometrics = await LocalAuthentication.getAvailableBiometrics();
if (availableBiometrics.contains(BiometricType.face)) {
  // Face ID.
} else if (availableBiometrics.contains(BiometricType.fingerprint)) {
  // Touch ID.
}

触发生物识别认证

使用默认对话框触发生物识别认证：

bool didAuthenticate = await LocalAuthentication.authenticateWithBiometrics(
  localizedReason: 'Please authenticate to show account balance',
);

如果不想使用默认对话框，可以将 useErrorDialogs 设置为 false：

bool didAuthenticate = await LocalAuthentication.authenticateWithBiometrics(
  localizedReason: 'Please authenticate to show account balance',
  useErrorDialogs: false,
);

你还可以自定义 iOS 的对话框消息：

import 'package:local_auth/auth_strings.dart';

const iosStrings = const IOSAuthMessages(
  cancelButton: 'cancel',
  goToSettingsButton: 'settings',
  goToSettingsDescription: 'Please set up your Touch ID.',
  lockOut: 'Please reenable your Touch ID',
);
await LocalAuthentication.authenticateWithBiometrics(
  localizedReason: 'Please authenticate to show account balance',
  iOSAuthStrings: iosStrings,
  useErrorDialogs: false,
);

停止认证

在 Android 上，你可以手动停止认证：

void _cancelAuthentication() {
    LocalAuthentication.stopAuthentication();
}

异常处理

该插件可能抛出以下几种异常：PasscodeNotSet, NotEnrolled, NotAvailable, 和 OtherOperatingSystem。它们都被封装在 LocalAuthenticationError 类中。例如：

import 'package:flutter/services.dart';
import 'package:local_auth/error_codes.dart' as auth_error;

try {
  bool didAuthenticate = await LocalAuthentication.authenticate(
    localizedReason: 'Please authenticate to show account balance',
  );
} on PlatformException catch (e) {
  if (e.code == auth_error.notAvailable) {
    // Handle this exception here.
  }
}

平台集成

iOS 集成

在 Info.plist 文件中添加以下内容以支持 Face ID：

<key>NSFaceIDUsageDescription</key>
<string>Why is my app authenticating using face id?</string>

Android 集成

在 AndroidManifest.xml 文件中添加以下权限：

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
          package="com.example.app">
  <uses-permission android:name="android.permission.USE_FINGERPRINT"/>
</manifest>

完整示例 Demo

以下是一个完整的示例应用，展示了如何使用 flutter_local_auth_invisible 插件进行生物识别认证：

import 'dart:async';
import 'package:flutter/material.dart';
import 'package:flutter/services.dart';
import 'package:flutter_local_auth_invisible/flutter_local_auth_invisible.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatefulWidget {
  [@override](/user/override)
  _MyAppState createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  String _authorized = 'Not Authorized';

  [@override](/user/override)
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(
          title: const Text('Plugin example app'),
        ),
        body: Column(
          mainAxisAlignment: MainAxisAlignment.spaceAround,
          children: [
            Text(
              'Can ${AuthProviderState.biometricsEnabled ? '' : 'not '}'
              'auth with biometrics',
            ),
            Text('Current State: $_authorized\n'),
            AuthProvider(
              'hash',
              onSuccess: () => setState(
                () => _authorized = 'Authorized',
              ),
            ),
          ],
        ),
      ),
    );
  }
}

class AuthProvider extends StatefulWidget {
  const AuthProvider(
    this.pinHash, {
    this.onFinishChecking,
    this.onStartChecking,
    this.onSuccess,
  });
  final Function()? onFinishChecking;
  final Function()? onStartChecking;
  final Function()? onSuccess;
  final String pinHash;

  [@override](/user/override)
  AuthProviderState createState() => AuthProviderState();
}

class AuthProviderState extends State<AuthProvider> {
  static bool biometricsEnabled = false;
  bool _biometricsSelected = true;
  List<BiometricType> _biometricSensors = [];
  String? _biometricsIcon;

  [@override](/user/override)
  void initState() {
    super.initState();
    WidgetsBinding.instance!.addPostFrameCallback((_) => _init());
  }

  Future<void> _init() async {
    _biometricSensors = await LocalAuthentication.getAvailableBiometrics();
    biometricsEnabled = (await LocalAuthentication.canCheckBiometrics) &&
        _biometricSensors.isNotEmpty;
    _biometricsIcon = _biometricSensors.contains(BiometricType.face)
        ? 'ui.faceId'
        : 'ui.fingerprint';
    setState(() {});
    await _launchScannerSchedule();
  }

  [@override](/user/override)
  void didUpdateWidget(oldWidget) {
    _launchScannerSchedule();
    super.didUpdateWidget(oldWidget);
  }

  [@override](/user/override)
  Widget build(BuildContext context) => Column(
        children: [
          biometricsEnabled && _biometricsSelected
              ? Text('BiometricsView()')
              : Text('PinPadView()'),
          TextButton(
            onPressed: _toggleView,
            child: Text('Toggle auth method'),
          ),
        ],
      );

  Future<void> _launchScannerSchedule() async {
    if (!biometricsEnabled) return;

    await LocalAuthentication.stopAuthentication();
    await Future.delayed(const Duration(milliseconds: 300), _launchScanner);
  }

  Future<void> _launchScanner() async {
    try {
      while (_biometricsSelected) {
        final didAuthenticate = await LocalAuthentication.authenticate(
          localizedReason:
              'Please pass the biometrical authentication to continue.',
          stickyAuth: false,
          useErrorDialogs: true,
        );
        if (didAuthenticate) {
          widget.onSuccess?.call();
          break;
        } else {
          await Future.delayed(const Duration(milliseconds: 500));
        }
      }
    } on PlatformException catch (_) {
      // Report the issue
    }
  }

  void _toggleView() {
    setState(() => _biometricsSelected = !_biometricsSelected);
    if (_biometricsSelected) {
      _launchScanner();
    } else {
      LocalAuthentication.stopAuthentication();
    }
  }
}