ScreenVeil #

A premium, lightweight, and highly customizable Flutter package designed to protect sensitive content when users switch apps or put your application into the background (app switcher preview).

ScreenVeil lets you easily mask or cover your active application screen with a Gaussian Blur, a Custom Image, or a Completely Custom Widget (like passcode screens or brand splash locks).

Features #

• Gaussian Blur Effect: Real-time adjustable blur (sigmaX & sigmaY) with customizable overlay colors.
• Image Backdrop: Cover your app switcher preview with beautiful assets or brand wallpapers.
• Custom Widgets: Render any custom Flutter widget (e.g., dynamic biometric scan prompt, PIN lock keypad).
• Zero Native Bloat: Written in pure Dart & Flutter, making it highly secure and compatible with all cross-platform channels.
• Auto Lifecycle Detection: Integrates with WidgetsBindingObserver to shield previews instantly.
• Manual Programmatic Lock: Use the forceShow parameter to trigger the veil screen during transaction processing or biometric checkpoints.
• Premium Micro-Animations: Smooth fade-in/fade-out animations with adjustable durations.

Architecture Flow #

graph TD
    App[Flutter Application] -->|Wrapped by| SV[ScreenVeil Widget]
    SV -->|Monitors App Lifecycle| Lifecycle[AppLifecycleState]
    
    Lifecycle -->|inactive / paused| ShowVeil[Immediately Overlay Veil]
    Lifecycle -->|resumed| HideVeil[Smoothly Dismiss Veil]
    
    ShowVeil --> Blur[VeilType.blur]
    ShowVeil --> Image[VeilType.image]
    ShowVeil --> Custom[VeilType.custom]

Getting Started #

1. Add dependency #

Add screenveil to your pubspec.yaml file:

dependencies:
  screenveil:
    path: ./path/to/screenveil

2. Wrap your Application #

Wrap the root widget of your application (or just the sensitive screen) with the ScreenVeil widget. Typically, wrapping your MaterialApp's nested Navigator or home page builder works best:

import 'package:flutter/material.dart';
import 'package:screenveil/screenveil.dart';

void main() => runApp(const MyApp());

class MyApp extends StatelessWidget {
  const MyApp({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: ScreenVeil(
        type: VeilType.blur,
        blurOptions: BlurVeilOptions(
          sigmaX: 15.0,
          sigmaY: 15.0,
          color: Colors.black.withOpacity(0.5),
          centerWidget: const Icon(Icons.lock, color: Colors.white, size: 50),
        ),
        child: const MyDashboard(),
      ),
    );
  }
}

Veil Types & Examples #

1. Blur Style (VeilType.blur) #

Fades in a soft glass-morphic Gaussian blur over your application content, keeping the general aesthetic while fully obfuscating text and numbers.

ScreenVeil(
  type: VeilType.blur,
  blurOptions: BlurVeilOptions(
    sigmaX: 12.0,
    sigmaY: 12.0,
    color: Color(0x990A0E17), // 0.6 opacity dark slate
    centerWidget: Column(
      mainAxisSize: MainAxisSize.min,
      children: [
        Icon(Icons.shield_rounded, color: Colors.cyan, size: 48),
        SizedBox(height: 12),
        Text('Secure Session Active', style: TextStyle(color: Colors.white)),
      ],
    ),
  ),
  child: Dashboard(),
)

2. Image Cover Style (VeilType.image) #

Replaces your background preview with a solid logo, branded graphic, or wallpaper.

ScreenVeil(
  type: VeilType.image,
  imageOptions: ImageVeilOptions(
    image: AssetImage('assets/images/secured_preview_wallpaper.png'),
    fit: BoxFit.cover,
    tintColor: Colors.black.withOpacity(0.4), // optional wash overlay
  ),
  child: Dashboard(),
)

3. Custom Widget Builder (VeilType.custom) #

Provides the ultimate control. Render passcode inputs, biometric lock controls, or marketing banners when the screen goes background.

ScreenVeil(
  type: VeilType.custom,
  customOptions: CustomVeilOptions(
    child: Scaffold(
      backgroundColor: Colors.black,
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            CircularProgressIndicator(),
            SizedBox(height: 16),
            Text('Encrypting memory data...'),
          ],
        ),
      ),
    ),
  ),
  child: Dashboard(),
)

API Parameters #

Best Practices for Complete Security #

While rendering a Flutter-level overlay works beautifully for protecting your app's screenshot preview in the native app switcher, it depends on the operating system capturing the frame after the inactive event is fully handled.

For absolute system-level protection (e.g., completely blocking screenshots and making the preview black or blank natively):

• Android: Combine ScreenVeil with the native FLAG_SECURE configuration:

  import 'package:flutter_windowmanager/flutter_windowmanager.dart';
  // ...
  await FlutterWindowManager.addFlags(FlutterWindowManager.FLAG_SECURE);
  

• iOS: Combine with native window cover adjustments or secure text field tricks if you want to block video recording and manual user screenshots altogether.