Permissions
One call site: the library reports the steps the user must allow as data, and
your onboarding explains each one. Which steps are listed depends on the
features you intend to use.
getScreenTimePermissionsAsync(options?)
The current status of every step the requested features need, without prompting.
const response = await ExpoScreenTime.getScreenTimePermissionsAsync({
features: ["blocking", "shieldOpenApp"],
});
// response.granted: boolean
// response.status: 'granted' | 'denied' | 'undetermined'
// response.canAskAgain: boolean
// response.steps: [
// { id: 'screenTime', status, required: true, kind: 'prompt', error? },
// { id: 'notifications', status, required: true, kind: 'prompt', error? },
// ]Options
| Option | Type | Default | |
|---|---|---|---|
features | ScreenTimeFeature[] | ['blocking', 'monitoring'] | What the app will use; decides which steps are listed and required. On iOS every feature rests on the screenTime step; shieldOpenApp adds the notifications step. On Android, blocking and monitoring need overlay and usageAccess; usageReports needs usageAccess; appRemovalProtection needs deviceAdmin. A feature the build does not contain (android.features) rejects UNSUPPORTED, naming it; the default narrows to the default features the build has. |
member | 'individual' | 'child' | 'individual' | child requests Family Sharing authorization for a child account, approved by a parent. On an account that is not a child in a family, the request fails with the step error invalidAccountType. iOS reads it only when requesting screenTime; Android makes the notifications and deviceAdmin steps required for a child (Google Play's parental-control rules demand a persistent notice), so it is read when listing the steps too. |
Steps on iOS
| Step | iOS | Status read from |
|---|---|---|
screenTime | Always listed, required. The Family Controls system prompt. | AuthorizationCenter |
notifications | Listed, and required, when features includes shieldOpenApp: a shield's openApp action reaches the app through a local notification the user taps. The prompt asks for alerts and sounds. | UNUserNotificationCenter (authorized, provisional and ephemeral are granted) |
Steps on Android
Android has no single Screen Time authorization: the enforcement engine rests
on special-access toggles the user flips in Settings, one screen each. The
library lists them in onboarding order; kind says how each one is granted.
A step is listed only when the build has what it grants: no overlay
without the shield, no deviceAdmin without its receiver, no engine steps
without the engine (the android.features
option removes them).
| Step | Listed for | Required | Kind | What it is |
|---|---|---|---|---|
overlay | blocking, monitoring (in a build with the shield) | yes | settings | Settings › Display over other apps. The shield is an Activity the engine launches from the background, which Android allows once this is held. Requested first: it also lets the library bring the user back to the app from the next screens. |
usageAccess | blocking, monitoring, usageReports | yes | settings | Settings › Usage access. How the engine sees which app is in the foreground. |
accessibility | blocking, in a build whose config plugin declared the accessibility service (android.accessibilityEngine) | no | settings | Settings › Accessibility: the service's own page where Android shows it (Android 10+), else the list. Turns on the second detector, which hears a blocked app opened from a work profile, Private Space or a cloned app; the main profile is enforced without it, which is why it is recommended, not required. Show your disclosure first (below). restricted when Android 17's Advanced Protection is on (it disables every accessibility service that is not an accessibility tool) or under restricted settings. |
notifications | blocking, monitoring (Android 13+) | for member: 'child' | prompt | The runtime notification permission for the engine's persistent notice. Without it the service still runs; the notice moves to the Task Manager. |
deviceAdmin | blocking, monitoring (in a build with the device admin), appRemovalProtection | for appRemovalProtection and member: 'child' | settings | Device admin activation (no policy). While active, Settings disables "Force stop", "Uninstall" asks to deactivate the admin first, and the system's Task Manager hides the engine's "Stop" button. Deactivating takes the toggle in Settings › Security › Device admin apps plus a confirmation whose text is the expo_st_device_admin_disable_warning string resource (override it in your app's res/values to localise it); it does not stop the engine. |
batteryOptimization | blocking, monitoring | no | settings | The system's battery-optimization list. The library opens the list and never requests REQUEST_IGNORE_BATTERY_OPTIMIZATIONS (not an acceptable use for a blocker on Google Play). With the exemption, an engine the system killed restarts directly from the background; without it, the library restarts it through the overlay permission, which is why overlay is required (see blocking). This step or deviceAdmin keeps the restart within minutes on battery: either one exempts the app from the standby buckets' alarm limit. |
backgroundAutostart | blocking, monitoring, on Xiaomi, Oppo, Realme, Vivo, Huawei, Honor and OnePlus | no | guide | The vendor's autostart screen. Nothing reads it back: its status stays unknown. |
A settings toggle that is off reads undetermined until the app has sent the
user to that screen once, and denied after, so an onboarding UI can tell
"never asked" from "went there and came back without it". restricted is
reported when Android 13+ keeps the toggles locked for a sideloaded app
("restricted settings", lifted from App info), for overlay on a low-RAM
device, where the system never grants it, and for accessibility under
Android 17's Advanced Protection. screenTime is never listed on Android,
and accessibility only in a build that opts into the accessibility engine.
A step's status adds two values to Expo's:
restricted: the OS refuses to let this user grant access (Screen Time restrictions, a managed device, Android's restricted settings). The response then reportsstatus: 'denied'andcanAskAgain: false; the user has to change the restriction in Settings.unknown: the status cannot be read back.
The response
Expo's PermissionResponse plus the ordered steps behind it:
grantedistruewhen everyrequiredstep isgranted;statusis'granted'if so; else'denied'if a required step isdeniedorrestricted; else'undetermined';canAskAgainistruewhen no required step isrestrictedand every required step still to grant can show its prompt. Family Controls shows its prompt again after a denial; the notification prompt is shown once, so a deniednotificationsstep readscanAskAgain: falseuntil the user allows it in Settings.
requestScreenTimePermissionsAsync(options?)
Advances onboarding by one step and resolves with the whole response:
options.step if given, else the first required step not yet granted. Call it
again for the next step, so your UI can explain each one. A step already
granted is not asked again; when nothing is pending, nothing is prompted.
On Android a settings or guide step opens its screen and the promise
resolves when the user comes back to the app, with fresh statuses. For
usageAccess and overlay the library also watches the toggle and brings
the app back the moment it flips, which Android honours once overlay is
held. For accessibility it watches the enabled-services setting the same way.
A screen that could not be opened (an ActivityNotFoundException on
an unusual device) is not an error: the step keeps it in error and the
response says so. A step the platform does not have (screenTime), or
accessibility in a build that does not declare the service, rejects with
INVALID_CONFIG.
The accessibility step and its disclosure
Google Play requires a prominent disclosure inside the app, before the
user is sent to Settings › Accessibility, during normal use (the store
listing or a website is not enough): what the service does, and the user's
consent. The library cannot show it for you (it is UI), and the step is
never part of the "first required step" default, so the only way to reach
it is an explicit step: "accessibility" call, which is where your
disclosure belongs:
import { Alert } from "react-native";
import { requestScreenTimePermissionsAsync } from "expo-screen-time";
function askForAccessibility() {
Alert.alert(
"Block apps everywhere on this phone",
"To block the apps you chose in your work profile, Private Space and " +
"cloned apps too, this app uses Android's Accessibility service. " +
"Android tells it when one of those apps opens, so it can show the " +
"blocking screen. It does not read what is on your screen, collects " +
"no personal data and sends nothing off your phone. You can turn it " +
"off at any time in Settings › Accessibility.",
[
{ text: "Not now", style: "cancel" },
{
text: "Continue to Settings",
onPress: () => requestScreenTimePermissionsAsync({ step: "accessibility" }),
},
],
);
}A French listing ships the same text in French:
Bloquer les applis partout sur ce téléphone — Pour bloquer aussi les applis choisies dans votre profil professionnel, votre Espace privé et vos applis clonées, cette appli utilise le service d'accessibilité d'Android. Android la prévient quand l'une de ces applis s'ouvre, afin d'afficher l'écran de blocage. Elle ne lit pas ce qui est à l'écran, ne collecte aucune donnée personnelle et n'envoie rien hors du téléphone. Vous pouvez la désactiver à tout moment dans Réglages › Accessibilité. [Continuer vers les Réglages] [Pas maintenant]
The disclosure's data sentence is this example's: keep it only if it is true
of your whole app. The Settings page shows the expo_st_accessibility_description
string next to the toggle; the library's default says only what the service
does (the window-state events, no screen content, the off switch), so add your
app's data practices in your override, and only true ones: Play reads it
against your declaration, so keep the two in step. Ask
the users who need the coverage (an app can check for other profiles
itself) rather than everyone: a chained settings screen loses users. The
response's granted never depends on this step. Once enabled, the lost
coverage while the service is down is reported by
getEnforcementGaps with
scope: "otherProfiles".
On iOS 16 and later it never rejects for a refused prompt: a failed request
resolves with the resulting status, and the reason in the step's error. A
step whose prompt the OS will not show again (a denied notifications step)
is not requested: the response comes back unchanged, with canAskAgain: false,
and your UI should send the user to Settings. Earlier iOS versions reject
with UNSUPPORTED; a step this platform does not have (an Android id), or
one the requested features do not list, rejects with INVALID_CONFIG.
// The first pending step (screenTime, then notifications)
let response = await ExpoScreenTime.requestScreenTimePermissionsAsync({
features: ["blocking", "shieldOpenApp"],
});
// A specific step, from a checklist
response = await ExpoScreenTime.requestScreenTimePermissionsAsync({
features: ["blocking", "shieldOpenApp"],
step: "notifications",
});Options
features and member as above, plus:
| Option | Type | |
|---|---|---|
step | PermissionStepId | The step to request. Default: the first required step not granted. |
await ExpoScreenTime.requestScreenTimePermissionsAsync({ member: "child" });The Screen Time authorization is device-wide: once granted, by either member, later requests resolve at once without a prompt.
Errors
error is present on a step when its last request failed: for screenTime,
code is the FamilyControlsError case name (restricted,
invalidAccountType, authorizationCanceled, networkError, unavailable,
…) and message its description; for notifications, an error thrown by the
request (a refusal is not an error: the step reads denied). It disappears
once the step is granted, and is kept for the app's lifetime only.
const response = await ExpoScreenTime.requestScreenTimePermissionsAsync();
const step = response.steps.find((s) => s.id === "screenTime");
if (step?.status === "restricted") {
// explain how to lift the restriction in Settings › Screen Time
} else if (step?.error?.code === "networkError") {
// offer to retry
}An onboarding checklist
import {
requestScreenTimePermissionsAsync,
useScreenTimePermissions,
type ScreenTimePermissionOptions,
} from "expo-screen-time";
import type { ReactNode } from "react";
import { Button } from "react-native";
const options: ScreenTimePermissionOptions = {
features: ["blocking", "shieldOpenApp"],
};
const titles: Record<string, string> = {
screenTime: "Allow Screen Time",
notifications: "Allow notifications",
overlay: "Allow display over other apps",
usageAccess: "Allow usage access",
accessibility: "Block apps in every profile",
deviceAdmin: "Activate device admin",
batteryOptimization: "Exempt from battery optimization",
backgroundAutostart: "Allow autostart",
};
function PermissionGate({ children }: { children: ReactNode }) {
const [permission, , refresh] = useScreenTimePermissions(options);
if (!permission) return null;
if (permission.granted) return children;
const pending = permission.steps.filter(
(step) => step.required && step.status !== "granted",
);
return (
<>
{pending.map((step) => (
<Button
key={step.id}
title={titles[step.id] ?? step.id}
onPress={async () => {
await requestScreenTimePermissionsAsync({ ...options, step: step.id });
await refresh();
}}
/>
))}
</>
);
}The same gate lists one step on iOS and several on Android, each requested
with one tap; recommended steps (required: false) make a good second
screen, after the app works.
useScreenTimePermissions(options?) Hook
Expo-style permissions hook for React components. options takes features
and member, plus the hook's own get and request flags; the request
method advances the first pending step.
function MyComponent() {
const [permission, requestPermission] = useScreenTimePermissions();
if (!permission?.granted) {
return <Button title="Grant Access" onPress={requestPermission} />;
}
return <Text>Permission granted!</Text>;
}