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.
| Platform | Status |
|---|---|
| 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. |
| Web | Not 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 itsselectionId;listSelections,getSelectionMetadata,getTokens,removeToken, the set operations andexportSelection/importSelectionwork as on iOS.<ApplicationLabel />renders an app's icon and name from a handle. Apps only:selectableKinds.categoriesandwebDomainsarefalse, so the picker has no category or web-domain rows andCategoryLabel/WebDomainLabelrender 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,isBlockedand 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 bygetEnforcementGaps(). An engine the system killed comes back by itself, within 3.5 minutes while the screen is on. On battery, that bound needs thedeviceAdminorbatteryOptimizationstep (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.accessibilityEngineadds an accessibility service next to the engine; once the user enables it (the recommendedaccessibilitystep, 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 withscope: "otherProfiles". Off by default: it puts the build under Google Play's AccessibilityService review. -
Monitoring.
startMonitoringand 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 andblockOnThreshold, 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 withtarget),isTemporarilyUnlocked,getRemainingUnlockSeconds,relock,setShieldActions/setShieldActionsForActivity(close, unblock, defer, snooze, a directopenApp) anddrainShieldInteractions. The engine meters the budget in exact seconds of use (meteringSecondsis 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 sameReport.*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 theusageAccesspermission step (requested with theusageReportsfeature) 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 (noQUERY_ALL_PACKAGES), the enforcement service in its own:screentimeprocess, the boot and update receivers and the device-admin receiver. Nothing to configure; two options (android.parentalControl, andandroid.featuresto 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-platformlimits;categories,webDomains,webDomainBlockingandopenApplicationare off.- Every function behind an off capability fails with a coded error.
Synchronous functions (
blockWebDomains…) throw it; asynchronous ones (openApplication…) reject with it.error.codeis"UNSUPPORTED"and the message names the function. - Components:
CategoryLabelandWebDomainLabelrender their placeholder;<DeviceActivityReport />renders its fallback only in a build whoseandroid.featuresleavesusageReportsout.
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.