Schedule Monitoring
Requires the `DeviceActivityMonitorExtension` target
See Target Selection.
startMonitoring(config: MonitoringConfiguration)
Start monitoring device activity with a schedule. When the interval starts, the
selection referenced by selectionId is blocked; when it ends, that block is
lifted. Each activity is its own block source: ending one interval never touches
the manual block (blockSelection), another schedule, or a web-domain filter —
the effective block is the union of every active source.
If the current time is already inside the interval, the block is applied at
once and an intervalDidStart event is recorded immediately (the system's own
callback fires asynchronously, at the first device use after the boundary).
await ExpoScreenTime.startMonitoring({
activityName: 'workHours',
schedule: {
intervalStart: { hour: 9, minute: 0 },
intervalEnd: { hour: 17, minute: 0 },
repeats: true,
warningTime: 300, // 5 minute warning before interval ends (seconds)
},
// Selection to block during the interval — a stored selection ID
selectionId: 'work-blocklist',
// Optional: how selectionId is applied — 'blocklist' (default) shields it,
// 'allowlist' shields every app EXCEPT its apps (applications only)
mode: 'blocklist',
// Optional usage thresholds within the interval
events: [
{
eventName: 'socialMediaLimit',
selectionId: 'social-apps', // stored selection to meter
threshold: 3600, // 1 hour, in seconds
includesPastActivity: false,
// Optional: shield 'social-apps' from the threshold until the interval ends
blockOnThreshold: true,
},
],
// Optional: restrict to specific weekdays (1 = Sunday … 7 = Saturday)
weekdays: [2, 3, 4, 5, 6],
});weekdays does not multiply activities: workHours above is one activity (one
of the 19 you can monitor at once, see below), its events are recorded under
workHours, and occurrences on Saturday and Sunday are ignored. A one-off
schedule (repeats: false) with weekdays covers its next occurrence on a
selected weekday — the one in progress when it is on a selected weekday —
rather than the next occurrence at all: the schedule above with
repeats: false, started on a Friday evening, blocks on Monday from 09:00 to
17:00. A blockOnThreshold shield
covers the event's selection (social-apps here, not the activity's
work-blocklist) and is lifted with the interval.
mode: 'allowlist' makes the interval a focus window: every app except the
selection's apps is shielded while it is active, with the same rules as
blockSelection's allowlist — applications only
(startMonitoring rejects INVALID_CONFIG for a selection with categories or
web domains, or for an allowlist without selectionId), the web shielded
whole, your app, Phone and Settings never shielded. blockOnThreshold events
of the same activity keep blocklist semantics: an app their selection lists
directly is shielded even if the allowlist allows it. A category in a
threshold selection cannot override the allowlist of its own activity (the
two share one store, where "every app except…" already covers the category
and an allowed app inside it cannot be told apart), so list the apps. The
selection is read live: editing it changes the running allowlist at the
next re-projection. temporaryUnlock without a target rejects UNSUPPORTED
while such an interval is active (a
targeted unlock of a shielded app works).
Activity names are free-form, except that they must not be empty, start with
expo_st_ (the module's own namespace — its temporary-unlock meter and its
shield-snooze meters live there) or contain __expo_st_gen_, which the
module appends to the name it registers with the system. startMonitoring
and stopMonitoring both reject such a name with INVALID_CONFIG.
You can monitor 19 activities at once
(limits.maxMonitoredActivities, the same on both
platforms): startMonitoring rejects a 20th activityName with
EXCESSIVE_ACTIVITIES before anything is registered. Starting an activity
that is already monitored replaces it and costs no slot. The limit comes from
iOS, which allows 20 DeviceActivities per app: the temporary-unlock meter
takes one while an unlock is in progress, and each shield
snooze in progress takes one, so keep fewer activities
if you rely on snoozes — when the meters hold the remaining slot,
startMonitoring rejects with EXCESSIVE_ACTIVITIES as well (the message
names the slots), and a snooze press cannot arm its meter (the shield stays).
Calling startMonitoring again with the same activityName updates the
activity in place: the new schedule, selection and events replace the old
ones, and an interval in progress keeps its shields throughout — no
intervalDidEnd/intervalDidStart pair is recorded for the swap — while its
blockOnThreshold shields are reset, since the new registration re-arms the
thresholds. Stopping an activity and starting it again right away is just as
safe: the system keeps reporting on a stopped registration for a moment, and
those late callbacks are ignored.
If startMonitoring rejects, the previous registration keeps running with its
previous settings. When the device is at the 20-activity limit the previous
registration has to be released before the new one can be tried; if the new
one then fails, the previous schedule is registered again as it was (its
interval in progress included). Should that fail as well, the call rejects
with MONITORING_ROLLBACK_FAILED and the activity is stopped: its
intervalDidEnd is recorded if an interval was in progress, and it is no
longer listed by getMonitoredActivities.
A schedule that is not daily — intervalStart and intervalEnd on different
weekdays, e.g. Friday 22:00 to Sunday 06:00 — is registered as given; its
block is applied when the system reports the interval start, not synchronously.
Replacing a daily schedule with such a schedule ends the daily interval in
progress (its intervalDidEnd is recorded and its shields are lifted) and the
new interval is applied when the system reports it — within moments when the
device is already inside it.
stopMonitoring(activityName: string)
await ExpoScreenTime.stopMonitoring('workHours');Stops the activity and lifts its shields (its intervalDidEnd is recorded if
an interval was in progress). Other activities, a manual block, the
temporary-unlock meter and the shield snoozes are untouched; a reserved name
rejects with INVALID_CONFIG.
stopAllMonitoring()
Stops every activity started with startMonitoring and lifts their shields.
A manual block (blockSelection) and web-domain filters stay in force. A
temporary unlock in progress (temporaryUnlock) is not affected: it keeps
metering and re-applies the remaining sources when its budget is spent; nor
are shield snoozes.
await ExpoScreenTime.stopAllMonitoring();getMonitoredActivities(): Promise<string[]>
The activities you started. Activities the module runs for itself (the temporary-unlock meter, the shield-snooze meters) are never listed.
const activities = await ExpoScreenTime.getMonitoredActivities();
// ['workHours', 'bedtime']Monitor Events
The monitor extension records an event each time something happens (interval
start/end, threshold reached…). See
MonitorEvent for the payload and event types.
useMonitorEvents(callback?) hook
Subscribe to events in real time from a component:
import { useMonitorEvents } from 'expo-screen-time';
function MonitorLog() {
const { events, isListening, clearEvents } = useMonitorEvents((event) => {
console.log('monitor event', event.activityName, event.eventType);
});
return <Text>{events.length} events</Text>;
}Keeps the latest 100 events in state. Several mounted hooks share one native
listener — native observation starts with the first subscriber and stops with
the last, managed by expo-modules-core. (Lower-level: subscribe to the module's
onMonitorEvent event with ExpoScreenTime.addListener.)
getMonitorEvents(activityName?: string, limit?: number): Promise<MonitorEvent[]>
Read stored events (default limit 100). Omit activityName for all activities.
const events = await ExpoScreenTime.getMonitorEvents('workHours', 50);
// [{ activityName: 'workHours', eventType: 'intervalDidStart', timestamp: 1234567890 }]clearMonitorEvents(activityName?: string)
await ExpoScreenTime.clearMonitorEvents('workHours'); // one activity
await ExpoScreenTime.clearMonitorEvents(); // allTiming
Monitor events fire when the device is first used after the schedule time — not exactly at the scheduled time.
Android
Monitoring works on Android with the same API; the engine behind blocking evaluates the schedules and measures the usage. What differs:
- The same API, the same codes.
startMonitoringvalidates in the iOS order with the iOS codes:INVALID_CONFIG(noactivityName, a reserved name, noschedule, an allowlist withoutselectionIdor over a selection that is not apps only),INVALID_DATE_COMPONENTS,INTERVAL_TOO_SHORT(under 15 minutes),INTERVAL_TOO_LONG(over a week),EXCESSIVE_ACTIVITIES(a 20th logical activity; the contract's limit is 19 on both platforms).stopMonitoring,stopAllMonitoring,getMonitoredActivities,getMonitorEvents,clearMonitorEventsand the liveonMonitorEventstream (useMonitorEvents) behave as on iOS, down togetMonitorEventsordering: one activity oldest first, all activities newest first. In a build the config plugin trimmed (android.features) every monitoring function rejectsUNSUPPORTEDwithoutmonitoring, and withmonitoringbut notblockingastartMonitoringthat would shield (aselectionId, ablockOnThresholdevent) rejectsUNSUPPORTEDtoo: such a build records events and thresholds only. - Schedules are a function of time. Android has no DeviceActivity: the
engine evaluates
block = f(now, schedules)at every wake and every foreground change, so a schedule starting now shields at once and records itsintervalDidStartsynchronously (as iOS does since fix 12), midnight wrap andweekdayswork the same, andrepeats: falsecovers the one occurrence in progress or next. Boundaries that fall while the screen is off are observed at an inexact alarm (no exact-alarm permission): anintervalDidEnddue at 17:00 may be recorded later — within the window Android gives inexact alarms, up to an hour for a boundary a day away, and at the next maintenance window in Doze — or at the next screen-on, whichever comes first; iOS records it at the first device use after the boundary. The shields themselves are exact at the moment of use: a boundary is also evaluated the moment the screen comes on and on every foreground change. A device off for days records nothing for the occurrences it missed, like iOS. - Events are exactly once. Every event is recorded in the same store write as the state that justifies it (the interval marker, the fired threshold), under a cross-process lock, so a process killed between a transition and its record, or the app and the engine observing the same boundary, never duplicate an event; ids are sequence numbers, unique per install.
- Usage thresholds are measured from the UsageStats event stream, exact
to the tick — no 30 s ladder: the selection counts while at least one of
its apps is in the foreground, an instant counts once however many of
them share the screen, and nothing counts while the screen is off.
includesPastActivityreads the OS's history for the part of the interval before the registration (needsusageAccess; the OS keeps about 10 days).blockOnThresholdshields the event's selection from the fire until the interval ends, and its shield shows the threshold's configuration (precedence: threshold, then the latest schedule, then the manual block — the iOS rule). unblockAlllifts every active block — the manual block, the schedules in progress and their fired thresholds — and monitoring keeps running: the interval's end is still recorded and the schedule shields again at its next start, as on iOS.stopAllMonitoringleaves the manual block alone.isBlocked()istrueduring a schedule-driven block.- The engine runs while anything is monitored (its persistent notice stays), polling the foreground only while the screen is on and a block or a threshold needs it. A monitored activity whose interval is not in progress costs one inexact alarm, nothing else.
- A
weekdayon one bound only rejectsINVALID_DATE_COMPONENTS(no platform defines that interval; iOS hands it to the system, which declines it). The weekly shape (weekdayon both bounds, Friday 22:00 to Sunday 06:00) is evaluated by the engine.