Secure Content
Protect sensitive Flutter UI from recording visibility, app switcher previews, and runtime risk states on Android and iOS. On iOS, screenshot events are detected and reported.
Screenshots
Android - Screen recording demo
iOS - Screenshot detection result
iOS - Screen recording demo
https://github.com/user-attachments/assets/0b4e10ac-d592-4b5b-92bf-72f51b2cf570
iOS - App switcher demo
https://github.com/user-attachments/assets/b6ef5914-eb3a-4e17-be0c-2f00538cffec
Features
- Screenshot detection and recording obscuring
- App switcher protection with configurable color and optional branding image (iOS)
- Android 14+ screenshot callback support
- Biometric-only or biometric/device credential authentication with a typed result
- Inactivity auto-lock for secure areas
- Integrity risk checks (root/jailbreak/debugger/emulator heuristics)
- Soft mode events and optional hard-block mode
- Sensitive clipboard with TTL-based auto-clear
- Risk-state watermark overlay (only shown when needed)
Installation
Requires Flutter 3.44+, Dart 3.11+, Android API 23+, and iOS 13+. iOS builds require a Swift 6 compiler (Xcode 16 or newer). Android host apps must compile against SDK 37 or later. The example uses AGP 9.3.3. The example and CI use Flutter 3.47.4, which requires iOS 15+. See the native toolchain for compiler versions and compatibility. AndroidX Core is constrained to 1.17.0 because newer releases remove the fingerprint implementation required by stable Biometric on Android 23–27.
dependencies:
secure_content: ^3.1.0
For Face ID authentication, add a usage description to the host app's
ios/Runner/Info.plist:
<key>NSFaceIDUsageDescription</key>
<string>Authenticate to access protected content.</string>
For biometric authentication on Android 23–27, the host activity must extend
FlutterFragmentActivity. The example uses this activity on all Android versions:
import io.flutter.embedding.android.FlutterFragmentActivity
class MainActivity : FlutterFragmentActivity()
On Android 23–27, the activity theme must also inherit from
Theme.AppCompat.DayNight.NoActionBar or another AppCompat theme. Set this parent
for LaunchTheme and NormalTheme in both values/styles.xml and
values-night/styles.xml. The example includes these themes.
Quick Start
import 'package:flutter/material.dart';
import 'package:secure_content/secure_content.dart';
SecureContentScope(
enabled: true,
protectInAppSwitcher: true,
appSwitcherColor: Colors.black,
policy: const SecureContentPolicy(
requireBiometricOnResume: true,
inactivityTimeout: Duration(seconds: 30),
enableIntegrityChecks: true,
hardBlockOnIntegrityRisk: false,
enableRiskWatermark: true,
watermarkText: 'CONFIDENTIAL',
),
onEvent: (event) {
debugPrint('Secure event: ${event.type.name}');
},
child: const YourSensitiveWidget(),
)
Authentication
SecureContent.authenticate shows one system prompt and returns its outcome:
final capability = await SecureContent.getBiometricCapability();
if (capability.isAvailable) {
final usesFace = capability.types.contains(SecureContentBiometryType.face);
final result = await SecureContent.authenticate(
reason: usesFace ? 'Unlock with Face ID' : 'Unlock with your fingerprint',
biometricOnly: true,
persistAcrossBackgrounding: true,
);
switch (result.status) {
case SecureContentAuthStatus.success:
unlock();
case SecureContentAuthStatus.canceled:
case SecureContentAuthStatus.failed:
break; // Stay locked. Show no error.
case SecureContentAuthStatus.temporaryLockout:
showError('Too many attempts. Wait a moment, then try again.');
case SecureContentAuthStatus.permanentLockout:
showError('Unlock your device with its passcode, then try again.');
default:
showError('Could not check your biometrics.');
}
}
With biometricOnly: true, the prompt accepts only a biometric. It never
offers the device passcode, PIN, or pattern, so a person who holds an unlocked
phone cannot use the passcode to get in:
- iOS uses
.deviceOwnerAuthenticationWithBiometricsand hides the "Enter Password" fallback button. - Android allows
BIOMETRIC_WEAK(which includesBIOMETRIC_STRONG) withoutDEVICE_CREDENTIAL, and shows a Cancel button. This matcheslocal_authwithbiometricOnly: true.
With the default biometricOnly: false, the prompt also accepts the device
credential where the platform allows it, as requestBiometricAuth and
SecureContentScope do. On Android this needs API 30+ with a
FragmentActivity, or API 29+ with a plain Activity; older versions accept
only a biometric.
| Status | Meaning |
|---|---|
success |
The person authenticated. |
failed |
The biometric was not recognized. |
canceled |
The person, the app, or the system closed the prompt. On iOS this includes Cancel and the fallback button. |
timeout |
The prompt timed out (Android). |
temporaryLockout |
Too many attempts. Biometrics return after a short wait (Android). |
permanentLockout |
Too many attempts. The device passcode is needed before biometrics work again. |
notEnrolled |
The device has biometric hardware but no biometric is enrolled. |
notAvailable |
Authentication cannot run on this device or platform. |
error |
Any other error. result.message has the platform description. |
With persistAcrossBackgrounding: true, a prompt that the system closes
because the app lost the foreground (the person switched apps, or a call or
Control Center covered it) opens again when the app is resumed. The returned
future then completes with that prompt's result. Without it, such a prompt
returns canceled. A cancel by the person always returns canceled. This
matches local_auth's persistAcrossBackgrounding.
Only one prompt runs at a time. Calls made while a prompt is up share it when
their options match. Otherwise a call waits for the current
prompt to close, then opens its own, so a prompt that accepts the passcode
never answers a biometric-only call. authenticate emits no biometric events
on SecureContent.events.
getBiometricCapability() reports isAvailable when a biometric is enrolled.
It stays true during a lockout, and authenticate reports the lockout.
types lists the sensors the device has (face, fingerprint, iris). On
iOS this comes from LAContext.biometryType. On Android it comes from the
device's declared features and is best effort; it is [unknown] when
biometrics work but no known sensor feature is declared.
Scope and Native Protection
SecureContentScope scopes the Flutter overlay, lock screen, and risk
watermark to its child. When the scope is enabled, it also enables native
capture protection for the current app window. Native protection is not
limited to the scope's child.
While a scope is locked or hard-blocked, its child cannot receive focus, pointer input, or accessibility actions. Its accessibility content is hidden until access is restored. Custom lock and hard-block builders must paint an opaque cover that fills the scope.
App Switcher Branding (iOS)
On iOS, when the app moves to the background, the multitasking snapshot and
biometric re-auth moment are covered by a privacy overlay. By default this is
a flat appSwitcherColor fill. Pass appSwitcherImageName to center one of
your host app's native asset-catalog images on that overlay, rendered as a
white-tinted template:
SecureContentScope(
enabled: true,
protectInAppSwitcher: true,
appSwitcherColor: Colors.black,
// Name of an image in the iOS app's asset catalog (Assets.xcassets).
appSwitcherImageName: 'AppSwitcherLogo',
child: const YourSensitiveWidget(),
)
The native iOS privacy cover always uses an opaque background. The alpha
component of appSwitcherColor does not make protected content visible.
Note:
appSwitcherImageNameis iOS-only. Android ignores it.
Android App Switcher Cover
Android uses FLAG_SECURE for capture protection and for the snapshot that
Recents stores. When protection is enabled and protectInAppSwitcher is true,
Android also sets the navigation-bar color to appSwitcherColor. While the
activity window does not have focus, Android covers the full window with an
opaque appSwitcherColor fill. When the window gets focus again, Android
removes the cover. The alpha component of appSwitcherColor is ignored.
A new window is not covered before Android first reports its focus, so the cover does not flash at launch. A window that is already shown without focus when the plugin attaches is covered at once. If the plugin opens a biometric prompt before the window's first focus report, it covers the window until the prompt ends or the window reports focus. If another window, such as the notification shade, has focus when a new window opens, the new window stays uncovered until its focus changes.
Each engine emits appSwitcherProtected when its cover request starts and
appSwitcherUnprotected when the request ends. A request also ends when
protection is disabled or the activity detaches. Detaching the engine ends its
request without more events. If two engines share a window, the window stays
covered while either request is active.
When the user opens Recents directly from the app, launchers on Android 12 and later can show the running app as a live preview instead of the stored snapshot. The cover hides protected content in this preview after the app window loses focus. With the Pixel launcher on Android 16, gesture navigation removes focus when the gesture starts, so the cover is in place for the whole animation. The Recents button removes focus after the animation starts, so the first frames of the animation can show the app. Other launchers can behave differently.
The cover also appears when the notification shade, a system dialog, a biometric prompt, or another window of the app (such as a native dialog) takes focus. While the cover is shown, the app content is hidden from accessibility services.
In multi-window mode, such as split screen, the app stays visible while another window has focus. Android does not add the cover in this mode, so the Recents live preview of a split-screen pair can show protected content.
The cover cannot hide a Flutter view that uses a transparent SurfaceView
(RenderMode.surface with TransparencyMode.transparent), because that
surface draws above the window. FlutterActivity with a transparent background
uses a TextureView, which the cover hides.
Global Protection
await SecureContent.setGlobalProtection(
true,
protectInAppSwitcher: true,
appSwitcherColor: Colors.black,
);
Clipboard TTL
await SecureContent.setSensitiveClipboard(
'one-time code: 123456',
clearAfter: const Duration(seconds: 10),
);
iOS uses system pasteboard expiration and keeps sensitive copies local to the
device. Automatic cleanup preserves newer clipboard entries, including a new
copy of the same text. A zero or negative clearAfter disables automatic expiry.
Android restricts clipboard access while an app is in the background. If cleanup cannot access the clipboard, it remains pending until the app can access it again. The requested TTL is not a guaranteed background deletion deadline on Android. Process termination can also prevent app-scheduled cleanup.
Events
Listen to all secure events globally:
SecureContent.events.listen((event) {
debugPrint('Secure event: ${event.type.name}');
});
Key event types include:
screenshotCapturedrecordingStarted/recordingStoppedbiometricAuthSucceeded/biometricAuthFailed/biometricUnavailableintegritySafe/integrityRiskDetectedclipboardSet/clipboardClearedappSwitcherProtected/appSwitcherUnprotectedidleLockActivated/idleLockReleased
Platform Support
| Feature | iOS | Android |
|---|---|---|
| Screenshot Prevention | ❌ | ✅ |
| Screen Recording Obscuring | ✅ | ✅ |
| Screenshot Detection Callback | ✅ | ✅ (Android 14+) |
| Screen Recording Start Callback | ✅ | ❌ |
| Screen Recording Stop Callback | ✅ | ❌ |
| Biometric Re-Auth | ✅ | ✅ |
| Inactivity Auto-Lock | ✅ | ✅ |
| Integrity Risk Check | ✅ | ✅ |
| Hard Block Mode | ✅ | ✅ |
| Sensitive Clipboard TTL | ✅ | ✅ |
| Risk-State Watermark | ✅ | ✅ |
| App Switcher Protection | ✅ | ✅ |
| Dynamic Security Toggle | ✅ | ✅ |
| Full App Protection | ✅ | ✅ |
Notes
- Android screenshot callback requires Android 14+.
- Visual capture protection does not mute audio in a screen recording. Mute audio separately in the recording or media layer.
- Android system clipboard "Copied to clipboard" toast is controlled by the OS and cannot be disabled by apps.
- Integrity checks are heuristic signals, not a guaranteed anti-tamper boundary.
- The iOS plugin supports CocoaPods and Swift Package Manager. Its native window integration uses UIKit; it does not require SwiftUI.
Example
See example/lib/main.dart for a complete implementation including:
- global protection toggle
- biometric trigger
- biometric-only unlock with
SecureContent.authenticate - integrity check trigger
- clipboard TTL action
- hard-block mode toggle
- secure scope with policy
License
This project is licensed under the MIT License - see the LICENSE file for details.