Skip to Content
expo-screen-time

Platform support

expo-screen-time runs on iOS and Android behind one API. On Android the restrictions are friction, not OS-enforced: a foreground service draws the shield, and the user can stop it from the system settings, which getEnforcementGaps() reports. Usage reports render on both platforms from the same templates.

PlatformStatus
iOS 16+Supported. Every API on this site is implemented.
Android 7+ (API 24)Supported for apps: the permission steps, the picker, the selection store and the token labels, blocking and the shield, monitoring, the temporary unlock, the shield actions, the enforcement gaps and the usage reports. getCapabilities().blocking is "friction". Categories, web domains and openApplication report their capability off and fail with the UNSUPPORTED error code.
WebNot supported.

What works on Android now

  • Selections. <ActivityPicker /> lists the apps the user can launch and the engine can block (icon and name, searchable, multi-select; the launcher, dialer, Settings and the other always-reachable apps are left out) and stores the choice natively under its selectionId; listSelections, getSelectionMetadata, getTokens, removeToken, the set operations and exportSelection / importSelection work as on iOS. <ApplicationLabel /> renders an app's icon and name from a handle. Apps only: selectableKinds.categories and webDomains are false, so the picker has no category or web-domain rows and CategoryLabel / WebDomainLabel render their placeholder. Details on the selections page and the components page.

  • getScreenTimePermissionsAsync() / requestScreenTimePermissionsAsync() list the Android steps with their real status (overlay, usageAccess, notifications, deviceAdmin, batteryOptimization, backgroundAutostart) and open the matching Settings screen one step at a time. Details on the permissions page.

  • Blocking and the shield. blockSelection (blocklist and apps-only allowlist), unblockAll, isBlocked and the shield configuration work as on iOS. An enforcement engine, a foreground service in its own process, detects the foreground app from UsageStats while a block is in force and draws the shield, a full-screen Activity, over it (about 120 ms after the app comes forward on a Pixel 8a). It is "friction": the user can stop the engine from the Task Manager or Settings, and such periods are reported by getEnforcementGaps(). An engine the system killed comes back by itself, within 3.5 minutes while the screen is on. On battery, that bound needs the deviceAdmin or batteryOptimization step (see blocking). Details on the blocking and shields pages.

  • Other profiles, as an opt-in. Usage access reports the main profile only, so a blocked app opened from a work profile, Private Space or a cloned app is invisible to the engine. A build with android.accessibilityEngine adds an accessibility service next to the engine; once the user enables it (the recommended accessibility step, after the app's own disclosure) those launches are shielded too, and the coverage lost while the service is down is reported as a gap with scope: "otherProfiles". Off by default: it puts the build under Google Play's AccessibilityService review.

  • Monitoring. startMonitoring and the rest of the monitoring page: schedules evaluated by the engine as a function of time (midnight wrap, weekdays, the iOS limits), exactly-once events, usage thresholds measured from UsageStats and blockOnThreshold, with the iOS block composition. Boundaries that fall with the screen off are observed at an inexact alarm.

  • Temporary unlock, snoozes and shield actions. temporaryUnlock (the whole block, or one app with target), isTemporarilyUnlocked, getRemainingUnlockSeconds, relock, setShieldActions / setShieldActionsForActivity (close, unblock, defer, snooze, a direct openApp) and drainShieldInteractions. The engine meters the budget in exact seconds of use (meteringSeconds is 1); the shield comes back by itself when the budget is spent.

  • Enforcement gaps. getEnforcementGaps() reports when a block was intended but not enforced: the user stopped the app (stoppedByUser), the system killed the engine or refused to restart it (killedBySystem), a reboot (unknown), or usage access / the overlay permission was revoked (permissionRevoked, open while it is). Details on the capabilities page.

  • Usage reports. <DeviceActivityReport /> renders the same Report.* templates as iOS, natively, from the device's UsageEvents: screen time, pickups (every screen wake), the longest session, the first pickup, hourly buckets, the top apps with their icons, and categories as declared by each app's developer (coarse: most are "Other"). It needs the usageAccess permission step (requested with the usageReports feature) and renders zeros without it. Values never reach JavaScript. Details on the templates page.

  • The config plugin prepares the app: the permissions the engine needs, the launcher and home <queries> intents (no QUERY_ALL_PACKAGES), the enforcement service in its own :screentime process, the boot and update receivers and the device-admin receiver. Nothing to configure; two options (android.parentalControl, and android.features to leave out what the app does not use) on the configuration page.

What is off on Android

The Android module declares the same functions, event and views as iOS, so a screen shared between the platforms does not crash at import or at render:

  • getCapabilities() answers: blocking: "friction", appRemovalProtection: "friction", appInstallationBlocking: "friction" (the engine shields the uninstall dialog, the stores and the package installer: restrictions), selectableKinds.applications: true, usageReports: true, shieldOpenApp: "direct", the cross-platform limits; categories, webDomains, webDomainBlocking and openApplication are off.
  • Every function behind an off capability fails with a coded error. Synchronous functions (blockWebDomains…) throw it; asynchronous ones (openApplication…) reject with it. error.code is "UNSUPPORTED" and the message names the function.
  • Components: CategoryLabel and WebDomainLabel render their placeholder; <DeviceActivityReport /> renders its fallback only in a build whose android.features leaves usageReports out.

Branch on capabilities rather than on the platform:

import { blockSelection, getCapabilities } from 'expo-screen-time';

function BlockButton({ selectionId }: { selectionId: string }) {
  if (getCapabilities().blocking === 'none') return null;
  return <Button title="Block" onPress={() => blockSelection(selectionId)} />;
}

UNSUPPORTED is part of the error-code vocabulary shared by both platforms, so a call that slips through can be caught the same way everywhere:

import { blockWebDomains, isScreenTimeError } from 'expo-screen-time';

try {
  blockWebDomains(['example.com']);
} catch (error) {
  if (isScreenTimeError(error) && error.code === 'UNSUPPORTED') {
    // not available on this platform
  } else {
    throw error;
  }
}

Roadmap

On Android, blocking and the shield, monitoring, the temporary unlock with the shield actions, the enforcement gaps, the engine's restart chain, the device-admin friction and the usage reports are in. The engine passed 24 h survival runs on a Pixel 8a and a Samsung Galaxy A54. Web-domain blocking is not available on Android yet.

On this page