← Prayer Lock Blog

Building an iOS app blocker with the Screen Time API (FamilyControls) in Expo: what the docs don't tell you

I spent the last few months building Prayer Lock, an iPhone app that blocks distracting apps during a scheduled daily prayer time. The whole product rests on Apple's Screen Time API: FamilyControls, ManagedSettings and DeviceActivity. The documentation is thin and the sharp edges are real. This is the write-up I wish I had on day one.

The app is React Native (Expo) with a native Swift module, but almost everything below applies to a pure Swift app too.

The three frameworks and who does what

Plus two extension points for the shield itself: ShieldConfigurationDataSource (how the shield looks) and ShieldActionDelegate (what its buttons do).

1. Authorization: individual, not parental

import FamilyControls

try await AuthorizationCenter.shared.requestAuthorization(for: .individual)

.individual is what you want for a self-control app. .child is for parental controls and requires Family Sharing. The entitlement com.apple.developer.family-controls must be requested from Apple through a form, and it's granted per bundle ID, so every app extension needs its own approval. Budget a week.

2. Tokens live in an App Group, not your database

FamilyActivitySelection is Codable, but the tokens inside are only meaningful on the device that produced them. Don't sync them to your backend. Store the selection in the shared container so extensions can read it:

static let appGroupId = "group.com.prayerlock.ios.shared"

func saveSelection(_ selection: FamilyActivitySelection) {
    let defaults = UserDefaults(suiteName: Self.appGroupId)
    defaults?.set(try? JSONEncoder().encode(selection), forKey: "selectedAppsData")
}

Every extension and the main app share one ManagedSettingsStore() keyed by the app group, so whoever applies the shield, the others see the same state.

3. Scheduling: the 15-minute floor and the dead-app problem

let schedule = DeviceActivitySchedule(
    intervalStart: DateComponents(hour: 7, minute: 0),
    intervalEnd:   DateComponents(hour: 7, minute: 30),
    repeats: true
)
try DeviceActivityCenter().startMonitoring(.prayerTime, during: schedule)

Things that cost me time:

class PrayerActivityMonitor: DeviceActivityMonitor {
    private let store = ManagedSettingsStore()

    override func intervalDidStart(for activity: DeviceActivityName) {
        guard let selection = AppBlockingManager.shared.loadSelection(),
              !hasPrayedToday() else { return }
        store.shield.applications = selection.applicationTokens
        store.shield.applicationCategories = .specific(selection.categoryTokens)
    }

    override func intervalDidEnd(for activity: DeviceActivityName) {
        store.shield.applications = nil
        store.shield.applicationCategories = nil
    }
}

4. The shield button cannot open your app. Full stop.

This is the one everyone hits. Your ShieldActionDelegate gets handle(action:for:completionHandler:) and may respond with .none, .close or .defer. There is no UIApplication, no NSExtensionContext, no URL opening. Apple Developer Forums thread 719905 and several Feedbacks confirm it across iOS 16–26. The private-API hacks you'll find on Stack Overflow don't work and will get you rejected.

What does work: the extension can post a local notification, and the user tapping that notification is the one sanctioned path back into your app.

override func handle(action: ShieldAction, for application: ApplicationToken,
                     completionHandler: @escaping (ShieldActionResponse) -> Void) {
    switch action {
    case .primaryButtonPressed:
        let defaults = UserDefaults(suiteName: appGroupId)
        defaults?.set(true, forKey: "shieldRequestedPrayer")
        defaults?.set(Date().timeIntervalSince1970, forKey: "shieldRequestedPrayerAt")

        let content = UNMutableNotificationContent()
        content.title = "Time to pray"
        content.body = "Tap to start your prayer."
        content.interruptionLevel = .timeSensitive
        UNUserNotificationCenter.current().add(
            UNNotificationRequest(identifier: "shield-prayer", content: content, trigger: nil))

        completionHandler(.close)
    default:
        completionHandler(.defer)
    }
}

Then, in the app, on AppState becoming active, read and clear the flag (with a freshness window, say five minutes) and route straight into the session. Two bugs this design produced for me, both invisible in testing:

  1. Notification permission was never requested on the path where users enabled blocking. Without it the button looks dead. Ask for notifications the moment Screen Time is granted, and show a banner with a Settings link if denied. .timeSensitive needs its own entitlement on the app and the shield-action extension.
  2. Cold-start race. My auth store set user before the profile finished loading; the shield consumer pushed the session screen, then the root redirect replaced it with Home. Gate the consumer on "auth fully loaded", not on "user exists".

5. The shield is a tint, not a background

ShieldConfiguration.backgroundColor is blended over the system material. A saturated orange renders as pale peach on device, and the simulator won't show you. Design the shield with dark text on a light base, use backgroundBlurStyle: .systemUltraThinMaterialLight, and put your brand color on the button, not behind the text. Localize the copy inside the extension; it doesn't see your app's i18n.

6. Wrapping it for Expo

The module is a standard Expo Module (expo-module.config.json + Swift). The pieces that need care:

AsyncFunction("scheduleBlocking") { (hour: Int, minute: Int, durationMinutes: Int, bufferMinutes: Int) -> Bool in
  ScheduleManager.shared.schedule(hour: hour, minute: minute,
                                  duration: durationMinutes, buffer: bufferMinutes)
}

What I'd tell past me

If you're building in this space, the Apple forums thread above is the best place to add your voice; the more Feedbacks on the shield-to-app handoff, the better the odds it changes.

I'm the developer of Prayer Lock. Everything above is from shipping it; corrections welcome in the comments.