DEV Community: Edward

How screenshot detection works on iOS

Edward — Tue, 07 Jul 2026 15:38:47 +0000

Detecting a screenshot on iOS starts with a single UIKit notification. That is the last easy part.

UIApplication.userDidTakeScreenshotNotification tells you a capture happened. It doesn't hand you the screenshot image, a view controller to present from or any promise that the new photo is already sitting in the library. Turning that one signal into a dependable bug-reporting flow is mostly about handling everything the notification leaves out.

I recently had to build exactly that. Here's what I learned.

There are really three steps

The notification is a starting gun, not a payload. Everything useful happens in the stages after it:

Observe UIKit's screenshot notification.
Capture the active key window and present the reporter with that image as a fallback.
If Photos access is available, find the recent screenshot asset and replace the fallback.

That separation matters. The notification tells me a capture happened. It does not give me the resulting UIImage, so I never write code that assumes it does.

Registering for the screenshot event

When detection is enabled, configuration starts a shared observer:

if enableScreenshotDetection {
    ScreenshotObserver.shared.startObserving()
}

The observer registers with NotificationCenter:

func startObserving() {
    guard !isObserving else { return }

    NotificationCenter.default.addObserver(
        self,
        selector: #selector(handleScreenshotNotification),
        name: UIApplication.userDidTakeScreenshotNotification,
        object: nil
    )

    isObserving = true
}

startObserving() and stopObserving() both guard their current state. Reconfiguring first tears down the old configuration, and shutdown stops the observer. I made both idempotent and wrote unit tests for repeated starts, repeated stops, stopping before a start and restarting after a stop.

The handler does no presentation work inline. It hops to the main queue, and the rest of the path is isolated to MainActor because it reads application state and touches UIKit:

@objc private func handleScreenshotNotification(_: Notification) {
    DispatchQueue.main.async { [weak self] in
        self?.presentBugReportIfNeeded()
    }
}

A screenshot event isn't automatically a safe moment to present UI

Before putting anything on screen, I check that:

the SDK is configured;
screenshot detection is still enabled;
the application is active;
a foreground-active scene has a key window;
that window has a root view controller; and
a reporter isn't already presented.

The window lookup is scene-aware, because assuming a single window hierarchy breaks the moment an app uses multiple scenes:

guard let scene = UIApplication.shared.connectedScenes
    .first(where: { $0.activationState == .foregroundActive }) as? UIWindowScene
else {
    return nil
}
return scene.windows.first(where: { $0.isKeyWindow })

From the root, I recursively follow presented view controllers, the visible controller in a navigation stack and the selected controller in a tab bar. That gives me a presenter matching the UI the user was actually looking at.

The duplicate-presentation guard walks that same top-most hierarchy looking for the reporter's hosting controller. If a report screen is already open, a second screenshot notification doesn't stack another one on top.

Capture a fallback before presenting anything

At notification time, the OS screenshot may not be available through Photos yet, and Photos access may never be granted at all. So I render the key window immediately:

private func captureWindowSnapshot(_ window: UIWindow) -> UIImage? {
    guard window.bounds.width > 0, window.bounds.height > 0 else { return nil }
    let renderer = UIGraphicsImageRenderer(bounds: window.bounds)
    return renderer.image { context in
        window.layer.render(in: context.cgContext)
    }
}

This uses CALayer.render(in:) rather than drawHierarchy(afterScreenUpdates:), and that choice cost me some debugging. SwiftUI-hosted windows can render blank through drawHierarchy because SwiftUI defers its layer-tree commits. Rendering the current layer tree works for both UIKit and SwiftUI windows.

I pass that image to the reporter and set an internal autoAttach flag:

let fallbackImage = captureWindowSnapshot(keyWindow)

BugScreenSDK.presentBugReport(
    from: topViewController,
    screenshot: fallbackImage,
    autoAttach: true
)

The fallback is captured before the reporter presents its own UI, so the attachment shows the host app rather than the report form covering it.

Photos permission is for the image, not the detection

When the report view first appears, its view model runs the auto-attach flow once and asks a dedicated coordinator for Photos access:

let status = PHPhotoLibrary.authorizationStatus(for: .readWrite)
switch status {
case .authorized, .limited:
    completion(.authorized)
case .denied, .restricted:
    completion(.denied)
case .notDetermined:
    showRationale(on: presenter, completion: completion)
@unknown default:
    completion(.denied)
}

For an undetermined status I show my own rationale alert first. "Continue" calls PHPhotoLibrary.requestAuthorization(for: .readWrite); "Not now" returns a cancelled outcome. The authorization callback returns to the main queue before I touch reporter state.

Only .authorized and .limited continue to the lookup. Denied, restricted, cancelled and unknown all simply leave the fallback in place. None of them block or dismiss the report. Detection never depended on Photos in the first place.

Finding the screenshot that caused the event

The view model records autoAttachSince when it's created. After authorization, it passes that timestamp to a locator that searches for a recent Photos asset classified as a screenshot:

let earliest = since.addingTimeInterval(-within)
let options = PHFetchOptions()
options.predicate = NSPredicate(
    format: "(mediaSubtypes & %d) != 0 AND creationDate >= %@",
    PHAssetMediaSubtype.photoScreenshot.rawValue,
    earliest as NSDate
)
options.sortDescriptors = [NSSortDescriptor(key: "creationDate", ascending: false)]
options.fetchLimit = 1

let result = PHAsset.fetchAssets(with: .image, options: options)

The default within is five seconds, so the lower bound starts five seconds before the view model's timestamp. Filtering on PHAssetMediaSubtype.photoScreenshot, ordering by creation date descending and requesting only the newest match keeps this from grabbing an ordinary photo or an unrelated old screenshot.

There's still a race between the UIKit notification and the asset actually appearing in Photos. If the first lookup returns nothing, I wait 750 milliseconds and try once more:

attempt(since: since, within: within) { image in
    if image != nil {
        completion(image)
        return
    }
    DispatchQueue.main.asyncAfter(deadline: .now() + 0.75) {
        attempt(since: since, within: within, completion: completion)
    }
}

One immediate attempt and one delayed attempt: a bounded retry, not a polling loop.

Requesting the image without an iCloud surprise

Once I have the asset, I ask PHImageManager for the full-size image:

let requestOptions = PHImageRequestOptions()
requestOptions.deliveryMode = .highQualityFormat
requestOptions.isNetworkAccessAllowed = false
requestOptions.isSynchronous = false
requestOptions.resizeMode = .none

PHImageManager.default().requestImage(
    for: asset,
    targetSize: PHImageManagerMaximumSize,
    contentMode: .default,
    options: requestOptions
) { image, info in
    // Inspect cancellation, errors, degraded results, and iCloud state.
}

Network access is off, so this never quietly downloads an iCloud-only image. The handler rejects cancellations and errors, rejects a degraded result when Photos reports the asset lives in iCloud, ignores other degraded callbacks and finishes with the non-degraded image.

I guard the completion with a didComplete flag and dispatch the result to the main queue, because Photos can invoke its result handler more than once.

Replace the fallback instead of attaching the same screen twice

The view model marks the initial screenshot as a placeholder only when autoAttach is on. If the Photos lookup succeeds, it upgrades that slot in place:

private func upgradePlaceholderOrAppend(with image: UIImage) {
    if let index = placeholderIndex, screenshots.indices.contains(index) {
        screenshots[index] = image
        return
    }
    let countBefore = screenshots.count
    addScreenshots([image])
    if screenshots.count > countBefore {
        placeholderIndex = screenshots.count - 1
    }
}

If there was no fallback, the OS screenshot is appended. If the user deleted the placeholder while the lookup was running, the image is appended subject to the four-attachment limit. Tests cover the replacement, the no-fallback path, permission denial and cancellation, a locator that returns no image and the rule that auto-attach runs only once per presentation.

What survived contact with production code

The production path is less about observing a notification than about preserving useful behaviour around it:

Treat userDidTakeScreenshotNotification as an event, not an image payload.
Keep observer start and stop idempotent.
Move UIKit work to the main actor and refuse to present outside an active scene.
Resolve the key window and top-most presenter instead of assuming one window hierarchy.
Prevent duplicate reporter presentation.
Capture an immediate, permission-free window snapshot before opening any SDK UI.
Make access to the saved OS screenshot a separate, optional Photos flow.
Filter by screenshot subtype and time, then retry once for the Photos write race.
Replace the fallback rather than showing two versions of the same capture.
Keep permission denial, an iCloud-only asset and lookup failure as recoverable outcomes.

iOS gives you a clean signal that a screenshot occurred. Everything else exists to turn that signal into a reliable attachment without making Photos access a prerequisite for reporting a bug.

I built this as the screenshot trigger in BugScreen, a bug-reporting SDK I'm building. It opens a report with the screenshot and relevant device context already attached, which is a much nicer payoff than all the notification plumbing suggests.

How screenshot detection works on Android

Edward — Tue, 07 Jul 2026 10:43:33 +0000

Detecting a screenshot on Android sounds like a single-callback problem. It isn't.

Android 14 introduced an official screenshot detection API, but supporting older releases still means watching MediaStore and deciding whether a newly added image looks like a screenshot. The two approaches provide different information, require different permissions and fail in different ways.

I recently had to implement both. Here's what I learned.

There are really two implementations

The first decision happens at runtime:

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
    // Bind ScreenCaptureCallback to the resumed Activity.
    val binder = ModernDetectorActivityBinder(onScreenshot)
    application.registerActivityLifecycleCallbacks(binder)
} else {
    // Observe new images in MediaStore.
    val detector = LegacyScreenshotDetector(context) { uri -> onScreenshot(uri) }
    detector.start()
}

This isn't just the usual compatibility branch around a renamed API. The behaviour on either side is fundamentally different:

Android version	How detection works	Permission needed for detection	Screenshot URI
Android 14+ (API 34+)	`Activity.ScreenCaptureCallback`	`DETECT_SCREEN_CAPTURE` (install-time)	Not provided
Android 5–13 (API 21–33)	`ContentObserver` on `MediaStore.Images`	Media-read permission (runtime)	Provided by the media change

The manifest needs to cover all of those versions:

<uses-permission
    android:name="android.permission.READ_EXTERNAL_STORAGE"
    android:maxSdkVersion="32" />
<uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
<uses-permission android:name="android.permission.DETECT_SCREEN_CAPTURE" />

READ_EXTERNAL_STORAGE is capped at API 32. Android 13 replaces it with READ_MEDIA_IMAGES. On Android 14+, neither is needed just to receive the capture event—but media permission may still be needed if the app wants the image itself.

Android 14 gives you a signal, not an image

The detector for Android 14 is tiny:

@RequiresApi(Build.VERSION_CODES.UPSIDE_DOWN_CAKE)
internal class ModernScreenshotDetector(
    private val activity: Activity,
    private val onScreenshotDetected: (Uri?) -> Unit,
) {
    val screenCaptureCallback = Activity.ScreenCaptureCallback {
        onScreenshotDetected(null)
    }

    fun start() {
        activity.registerScreenCaptureCallback(
            activity.mainExecutor,
            screenCaptureCallback,
        )
    }

    fun stop() {
        activity.unregisterScreenCaptureCallback(screenCaptureCallback)
    }
}

There are two catches hidden in that small amount of code.

The first is that ScreenCaptureCallback only reports that a capture happened. It doesn't return a bitmap or a content URI. Detection and access to the screenshot are separate operations, with separate permission requirements.

The second is that registration belongs to an Activity, not the Application. Keeping one detector around forever would either miss screenshots after the user moved to another activity or retain an activity that should have been released.

I used Application.ActivityLifecycleCallbacks to make the detector follow whichever activity is in the foreground:

override fun onActivityResumed(activity: Activity) {
    bind(activity)
}

override fun onActivityPaused(activity: Activity) {
    if (activity === boundActivity) stopCurrent()
}

fun bind(activity: Activity) {
    if (activity === boundActivity && current != null) return
    stopCurrent()
    current = ModernScreenshotDetector(activity, onScreenshotDetected).also {
        it.start()
    }
    boundActivity = activity
}

The identity checks make lifecycle churn harmless. Binding the same resumed activity twice does nothing; moving to a different activity unregisters the old callback before registering the new one. I also made start() and stop() idempotent and tested repeated starts, stopping before a start, and registering again after a stop.

There is a slightly awkward startup case too. An SDK can be initialized after the first activity has already resumed, in which case waiting for the next lifecycle callback is too late. I track the current foreground activity during AndroidX Startup so the detector can bind immediately. If a host app removes the Startup provider, it still binds normally on the next resume.

Finding the image is a separate job

When the Android 14 callback fires, I open the reporter and then separately try to find the newly created screenshot in MediaStore.

That lookup requires READ_MEDIA_IMAGES. Without it, BugScreen can ask for permission or fall back to Android's photo picker; the missing permission shouldn't prevent the report itself from opening.

With permission, the lookup filters the screenshots directory and asks for its newest row:

val selection =
    "${MediaStore.Images.Media.RELATIVE_PATH} LIKE ?"
val selectionArgs = arrayOf("%Screenshots%")

val args = Bundle().apply {
    putString(ContentResolver.QUERY_ARG_SQL_SELECTION, selection)
    putStringArray(ContentResolver.QUERY_ARG_SQL_SELECTION_ARGS, selectionArgs)
    putString(
        ContentResolver.QUERY_ARG_SQL_SORT_ORDER,
        "${MediaStore.Images.Media.DATE_ADDED} DESC",
    )
    putInt(ContentResolver.QUERY_ARG_LIMIT, 1)
}

On API 29 and later I filter on RELATIVE_PATH; older versions need the deprecated DATA column. On API 26 and later I use the bundle query API because Android 11 rejects the old trick of appending LIMIT 1 to the SQL sort order.

I search from five seconds before the callback time. The media row can be written just before the capture callback arrives, so using the event time as a hard lower bound occasionally misses the correct image. After querying, I still check DATE_ADDED and reject the result if it is too old.

Failures—including a missing permission—become a missing attachment rather than an app crash. This distinction ended up being the most useful design rule in the whole implementation: the platform callback is a signal; retrieving the image is an optional, recoverable operation with its own consent flow.

Before Android 14, watch MediaStore and make an educated guess

Older versions have no screenshot callback. I register a descendant-aware ContentObserver on the external images collection instead:

contentResolver.registerContentObserver(
    MediaStore.Images.Media.EXTERNAL_CONTENT_URI,
    true,
    observer,
)

That observer sees every new image, not just screenshots. Each change has to be classified by querying its DISPLAY_NAME, DATA and DATE_ADDED.

First, the image must be recent:

val currentTimeSeconds = currentTimeMillis() / 1000
if (currentTimeSeconds - dateAdded > 5) return false

Then its display name or path has to contain something screenshot-shaped:

val screenshotKeywords = listOf(
    "screenshot",
    "screen_shot",
    "screencap",
    "screen_capture",
    "screen-",
    "/screenshots/",
    "/screencapture/",
)

The comparison is case-insensitive. A normal camera image doesn't match; an oddly named image inside Pictures/Screenshots does.

This will always be a heuristic. Manufacturers can choose different filenames and storage locations, and DATA is legacy storage metadata. Supporting Android releases without a dedicated callback means accepting that there is no perfect signal.

MediaStore is noisy

One screenshot write can generate more than one observer notification. Without a debounce, a single screenshot can open the reporter twice.

val currentTime = currentTimeMillis()
if (currentTime - lastScreenshotTime < 1_000L) return@launch

if (isScreenshot(uri)) {
    lastScreenshotTime = currentTime
    delay(100) // Let the file finish writing.
    handler.post { onScreenshotDetected(uri) }
}

Only a successfully classified screenshot updates lastScreenshotTime. An unrelated photo therefore can't suppress a real screenshot that arrives immediately after it.

The classification runs on an IO coroutine. After a short delay to let the file finish writing, the callback returns to the main thread. When detection stops, I unregister the observer and cancel its child jobs so that queued work can't deliver a stale callback. I leave the injected scope itself alive, which allows the same detector to stop and start again.

The permissions answer depends on the question

I initially found it useful to split the permission helper in two:

fun getRequiredPermission(): String? =
    if (SDK_INT >= 34) null else getMediaReadPermission()

fun getMediaReadPermission(): String =
    if (SDK_INT >= 33) READ_MEDIA_IMAGES else READ_EXTERNAL_STORAGE

getRequiredPermission() answers “what is required to detect a screenshot?” On Android 14 the answer is no runtime permission, because DETECT_SCREEN_CAPTURE is granted at install time.

getMediaReadPermission() answers “what is required to retrieve the saved image?” On Android 14 that is still READ_MEDIA_IMAGES.

Conflating those questions leads either to unnecessary permission prompts or to code that assumes the modern callback contains an image. It doesn't.

What survived contact with production code

The complete implementation is mostly a collection of edges around two fairly small APIs:

Branch at API 34 because both the detection mechanism and permission model change.
Follow the resumed activity because ScreenCaptureCallback isn't application-scoped.
Treat detection and access to the saved image as separate capabilities.
On older Android versions, classify recent MediaStore rows instead of trusting raw observer events.
Expect duplicate notifications and files that are not quite finished writing.
Make registration, cleanup, permission denial and query failure safe to repeat or recover from.

Android 14 removed the guesswork from knowing a capture occurred. It didn't remove the lifecycle work, the optional image lookup or the need to support older devices.

I implemented this as the screenshot trigger in BugScreen, a bug-reporting SDK I'm building. It opens a report with the screenshot and relevant device context already attached—which is a much nicer payoff than all the lifecycle plumbing suggests.