@capgo/capacitor-privacy-screen

Protect sensitive app content from appearing in Android screenshots and iOS app-switcher previews.

Capgo's Privacy Screen plugin is a Capacitor port of PrivacyScreenPlugin with a modern native implementation for Capacitor 8.

Documentation

The most complete doc is available here: https://capgo.app/docs/plugins/privacy-screen/

Compatibility

| Plugin version | Capacitor compatibility | Maintained | | -------------- | ----------------------- | ---------- | | v8.*.* | v8.*.* | ✅ | | v7.*.* | v7.*.* | On demand | | v6.*.* | v6.*.* | ❌ |

Note: The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation. Only the latest major version is actively maintained.

Install

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-privacy-screen` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

npm install @capgo/capacitor-privacy-screen
npx cap sync

Configuration

Protection is disabled by default. Enable it on native startup with Capacitor config:

import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'Example',
  webDir: 'dist',
  plugins: {
    PrivacyScreen: {
      enabled: true,
      android: {
        dimBackground: true,
        privacyModeOnActivityHidden: 'splash',
      },
      ios: {
        blurEffect: 'dark',
      },
    },
  },
};

export default config;

Usage

import { PrivacyScreen } from '@capgo/capacitor-privacy-screen';

await PrivacyScreen.enable({
  android: {
    dimBackground: true,
    privacyModeOnActivityHidden: 'splash',
  },
  ios: {
    blurEffect: 'dark',
  },
});

const { enabled } = await PrivacyScreen.isEnabled();

await PrivacyScreen.disable();

await PrivacyScreen.enable();

// Perform a flow where screenshots or previews should be protected.

await PrivacyScreen.disable();

Use JavaScript calls when protection should only apply to specific screens or flows.

Behavior

• Android uses WindowManager.LayoutParams.FLAG_SECURE, which hides app content from screenshots, screen recording, and the recent apps preview.
• Android can show a temporary dim or splash overlay for recent-apps and activity-hidden states.
• iOS places app content in a secure rendering subtree while enabled and adds a temporary overlay while the app resigns active so the app-switcher snapshot does not expose your content, with optional light or dark blur.
• Web keeps an in-memory enabled flag for API parity, but browsers cannot enforce native privacy-screen behavior.

API

• enable(...)
• disable()
• isEnabled()
• getPluginVersion()
• Interfaces

Capacitor API for protecting app content from screenshots, screen recording, and native app-switcher previews.

enable(...)

enable(config?: PrivacyScreenConfig | undefined) => Promise<PrivacyScreenActionResult>

Enables privacy screen protection.

On Android this sets FLAG_SECURE, which also blocks screenshots and screen recording. On iOS this places app content in a secure rendering subtree while enabled and adds an overlay while the app is backgrounded so app content does not appear in the app-switcher snapshot.

| Param | Type | Description | | ------------ | ------------------------------------------------------------------- | ------------------------------------ | | config | PrivacyScreenConfig | Optional platform-specific behavior. |

Returns: Promise<PrivacyScreenActionResult>

disable()

disable() => Promise<PrivacyScreenActionResult>

Disables privacy screen protection.

Use this only when you explicitly want the current screen to remain visible in system previews.

Returns: Promise<PrivacyScreenActionResult>

isEnabled()

isEnabled() => Promise<PrivacyScreenStatus>

Returns the current enabled state.

Returns: Promise<PrivacyScreenStatus>

getPluginVersion()

getPluginVersion() => Promise<PluginVersionResult>

Returns the native implementation version marker.

Returns: Promise<PluginVersionResult>

Interfaces

PrivacyScreenActionResult

Result returned when privacy protection is toggled.

| Prop | Type | Description | | ------------- | -------------------- | --------------------------------------- | | success | boolean | Whether the native operation completed. |

PrivacyScreenConfig

Native startup and runtime configuration for privacy protection.

| Prop | Type | Description | Default | | ------------- | ---------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------ | | enabled | boolean | Enable privacy protection automatically when the native plugin loads. This option is read from Capacitor config only. | false | | android | { dimBackground?: boolean; preventScreenshots?: boolean; privacyModeOnActivityHidden?: 'none' | 'dim' | 'splash'; } | Android-only behavior. | | | ios | { blurEffect?: 'none' | 'light' | 'dark'; } | iOS-only behavior. | |

PrivacyScreenStatus

Current privacy screen state.

| Prop | Type | Description | | ------------- | -------------------- | ------------------------------------------------ | | enabled | boolean | Whether privacy protection is currently enabled. |

PluginVersionResult

Plugin version payload.

| Prop | Type | Description | | ------------- | ------------------- | ----------------------------------------------------------- | | version | string | Version identifier returned by the platform implementation. |