expo-app-blocker 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 expo-app-blocker contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,354 @@
+# expo-app-blocker
+
+Cross-platform app blocking module for Expo. Block other apps and redirect users to your app.
+
+**Android**: UsageStatsManager + Foreground Service + System Overlay
+**iOS**: Screen Time API (FamilyControls + ManagedSettings + DeviceActivity)
+
+## Features
+
+- Block specific apps from being used
+- Detect when a blocked app is opened (Android: polling, iOS: system shield)
+- Customizable iOS shield overlay (icon, title, subtitle, button text, colors)
+- Temporary unlock with timer
+- Auto-relock when unlock period expires (iOS DeviceActivityMonitor extension)
+- Notification when blocked app is detected
+- Persist blocked apps across app restarts
+- Native view for rendering blocked app names/icons on iOS (Apple's opaque tokens)
+- Automatic iOS extension target creation via `@bacons/apple-targets`
+- Full Expo Config Plugin - no manual native setup required
+
+## Prerequisites
+
+### Apple Developer Portal (iOS)
+
+1. Register **4 App IDs** with **Family Controls** and **App Groups** capabilities:
+   - `com.yourapp.id` (main app)
+   - `com.yourapp.id.DeviceActivityMonitor`
+   - `com.yourapp.id.ShieldAction`
+   - `com.yourapp.id.ShieldConfiguration`
+
+2. Create an **App Group**: `group.com.yourapp.blocker` (or your chosen identifier)
+
+3. Assign the App Group to all 4 App IDs
+
+4. Request **Family Controls** capability approval (works in dev builds without approval)
+
+### Android
+
+No special setup required beyond what the config plugin handles automatically.
+
+## Installation
+
+```bash
+npx expo install expo-app-blocker
+```
+
+> `@bacons/apple-targets` is included as a dependency for automatic iOS extension target creation.
+
+## Configuration
+
+Add the plugin to your `app.json`:
+
+```json
+{
+  "expo": {
+    "scheme": "myapp",
+    "ios": {
+      "bundleIdentifier": "com.yourapp.id",
+      "appleTeamId": "YOUR_TEAM_ID"
+    },
+    "android": {
+      "package": "com.yourapp.id"
+    },
+    "plugins": [
+      ["expo-app-blocker", {
+        "ios": {
+          "appGroup": "group.com.yourapp.blocker",
+          "shield": {
+            "title": "Hold on!",
+            "subtitle": "{appName} is blocked.",
+            "primaryButtonLabel": "Earn Free Time",
+            "secondaryButtonLabel": "Not now",
+            "primaryButtonColor": "#7cb518",
+            "icon": "./assets/shield-icon.png"
+          }
+        }
+      }]
+    ]
+  }
+}
+```
+
+### Plugin Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `ios.appGroup` | `string` | Required | App Group identifier for shared data |
+| `ios.shield.title` | `string` | `"Hold on!"` | Shield overlay title |
+| `ios.shield.subtitle` | `string` | `"{appName} is blocked."` | Shield subtitle. `{appName}` is replaced with the blocked app name |
+| `ios.shield.primaryButtonLabel` | `string` | `"Earn Free Time"` | Primary button text |
+| `ios.shield.secondaryButtonLabel` | `string\|null` | `"Not now"` | Secondary button text. Set to `null` to hide |
+| `ios.shield.primaryButtonColor` | `string` | `"#7cb518"` | Primary button background color (hex) |
+| `ios.shield.backgroundBlurStyle` | `string` | `"systemThickMaterial"` | iOS blur style |
+| `ios.shield.icon` | `string` | SF Symbol | Path to custom shield icon PNG (relative to project root, e.g. `"./assets/shield-icon.png"`) |
+| `android.notificationTitle` | `string` | `"App Blocked"` | Notification title |
+| `android.notificationText` | `string` | `"{appName} is blocked."` | Notification text |
+
+### EAS Build
+
+For EAS Build, declare extensions for credential management:
+
+```json
+{
+  "extra": {
+    "eas": {
+      "build": {
+        "experimental": {
+          "ios": {
+            "appExtensions": [
+              {
+                "targetName": "DeviceActivityMonitor",
+                "bundleIdentifier": "com.yourapp.id.DeviceActivityMonitor",
+                "entitlements": {
+                  "com.apple.developer.family-controls": true,
+                  "com.apple.security.application-groups": ["group.com.yourapp.blocker"]
+                }
+              },
+              {
+                "targetName": "ShieldAction",
+                "bundleIdentifier": "com.yourapp.id.ShieldAction",
+                "entitlements": {
+                  "com.apple.developer.family-controls": true,
+                  "com.apple.security.application-groups": ["group.com.yourapp.blocker"]
+                }
+              },
+              {
+                "targetName": "ShieldConfiguration",
+                "bundleIdentifier": "com.yourapp.id.ShieldConfiguration",
+                "entitlements": {
+                  "com.apple.developer.family-controls": true,
+                  "com.apple.security.application-groups": ["group.com.yourapp.blocker"]
+                }
+              }
+            ]
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## Build
+
+```bash
+# Generate native projects
+npx expo prebuild --clean
+
+# Run on Android
+npx expo run:android
+
+# Run on iOS (physical device required for Screen Time APIs)
+npx expo run:ios --device
+```
+
+## API Reference
+
+### Permissions
+
+```typescript
+import { getPermissionStatus, requestPermissions } from 'expo-app-blocker';
+
+// Check current permission status
+const status = await getPermissionStatus();
+// Returns: { allGranted: boolean, details: AndroidPermissions | IOSPermissions }
+
+// Request permissions (iOS: triggers Screen Time authorization)
+const result = await requestPermissions();
+```
+
+### Android: Permission Settings
+
+```typescript
+import { openOverlaySettings, openUsageStatsSettings } from 'expo-app-blocker';
+
+// Open system settings for overlay permission
+openOverlaySettings();
+
+// Open system settings for usage access
+openUsageStatsSettings();
+```
+
+### Android: App Blocking
+
+```typescript
+import { setBlockedApps, getBlockedApps, getInstalledApps } from 'expo-app-blocker';
+
+// Get list of installed apps
+const apps = await getInstalledApps();
+// Returns: [{ packageName: string, name: string }]
+
+// Set which apps to block (by package name)
+setBlockedApps(['com.instagram.android', 'com.google.android.youtube']);
+
+// Get currently blocked apps
+const blocked = getBlockedApps();
+// Returns: ['com.instagram.android', 'com.google.android.youtube']
+```
+
+### Android: Monitoring Control
+
+```typescript
+import { startMonitoring, stopMonitoring } from 'expo-app-blocker';
+
+// Start the foreground service (auto-started on module init)
+startMonitoring();
+
+// Stop monitoring
+stopMonitoring();
+```
+
+### iOS: App Selection
+
+```typescript
+import { presentFamilyActivityPicker } from 'expo-app-blocker';
+
+// Opens the iOS system app/category picker
+const items = await presentFamilyActivityPicker();
+// Returns: IOSBlockedItem[] - opaque tokens for selected apps/categories
+```
+
+### iOS: Block Configuration
+
+```typescript
+import { setBlockConfiguration, getBlockConfiguration, clearAllBlocks } from 'expo-app-blocker';
+
+// Apply blocks (shields appear on selected apps)
+await setBlockConfiguration({
+  blockedItems: items, // from presentFamilyActivityPicker()
+  isActive: true,
+});
+
+// Get current configuration
+const config = getBlockConfiguration();
+
+// Remove all blocks
+clearAllBlocks();
+```
+
+### iOS: Temporary Unlock
+
+```typescript
+import {
+  temporaryUnlock,
+  isTemporarilyUnlocked,
+  getRemainingUnlockTime,
+  relockApps,
+} from 'expo-app-blocker';
+
+// Unlock for N minutes (removes shields temporarily)
+const result = await temporaryUnlock(15);
+// Returns: { unlocked: boolean, expiresAt: number }
+
+// Check if currently unlocked
+const unlocked = isTemporarilyUnlocked();
+
+// Get remaining seconds
+const seconds = getRemainingUnlockTime();
+
+// Re-lock immediately
+await relockApps();
+```
+
+### iOS: Shield Button Events
+
+```typescript
+import { addPendingUnlockListener, checkAndClearPendingUnlock } from 'expo-app-blocker';
+
+// Check if user tapped shield button while app was closed
+const hasPending = checkAndClearPendingUnlock();
+
+// Listen for real-time shield button taps
+const subscription = addPendingUnlockListener(() => {
+  // User tapped "Earn Free Time" on the shield
+  // Navigate to your unlock/quiz screen
+});
+
+// Clean up
+subscription?.remove();
+```
+
+### iOS: Native Blocked Apps List
+
+Renders blocked app tokens with real names and icons using Apple's native Label view:
+
+```typescript
+import { BlockedAppsNativeList } from 'expo-app-blocker';
+
+// In your component
+<BlockedAppsNativeList
+  items={blockedItems}
+  selectionData={selectionBase64}
+  style={{ minHeight: 200 }}
+/>
+```
+
+## Platform Notes
+
+### iOS Limitations
+
+- **Physical device required** - Screen Time APIs don't work in the simulator
+- **App tokens are opaque** - You cannot extract app names/bundle IDs from tokens. Use `BlockedAppsNativeList` to render them with Apple's native Label
+- **FamilyActivityPicker is required** - No API to enumerate installed apps on iOS
+- **Shield customization is limited** - Only icon, title, subtitle, button labels, and colors can be changed. No custom views, fonts, or animations
+- **Cannot open apps from shield** - Use notifications as a workaround to redirect users to your app
+
+### Android Limitations
+
+- **~500ms detection delay** - The foreground polling interval means a blocked app is briefly visible before the overlay appears
+- **Overlay permission requires manual grant** - Users must enable "Display over other apps" in system settings
+- **Usage access permission requires manual grant** - Users must enable in system settings
+- **OEM battery optimizations** - Some manufacturers (Xiaomi, Samsung, etc.) may kill the foreground service. Users may need to disable battery optimization for your app
+
+### Android Permissions (auto-added by config plugin)
+
+| Permission | Purpose |
+|---|---|
+| `SYSTEM_ALERT_WINDOW` | Display blocking overlay |
+| `FOREGROUND_SERVICE` | Run monitoring service |
+| `FOREGROUND_SERVICE_SPECIAL_USE` | Required for Android 14+ |
+| `PACKAGE_USAGE_STATS` | Detect foreground app |
+| `RECEIVE_BOOT_COMPLETED` | Auto-start service on boot |
+| `POST_NOTIFICATIONS` | Show blocked app notifications |
+
+## How It Works
+
+### Android Flow
+
+1. `ExpoAppBlockerModule` starts `AppBlockerService` as a foreground service
+2. Service polls `UsageStatsManager` every 500ms to detect the foreground app
+3. If the foreground app is in the blocked list:
+   - A full-screen overlay covers the screen
+   - A notification is sent with a deep link to your app
+   - Your app is brought to the foreground
+4. Blocked apps are persisted in SharedPreferences
+
+### iOS Flow
+
+1. User authorizes Screen Time via `requestPermissions()`
+2. User selects apps to block via `presentFamilyActivityPicker()`
+3. `setBlockConfiguration()` applies shields via `ManagedSettingsStore`
+4. When a blocked app is opened, iOS shows the shield overlay (customized via `ShieldConfigurationExtension`)
+5. When the user taps the shield button, `ShieldActionExtension` sends a notification via Darwin notification center
+6. Your app receives the event and can navigate to an unlock flow
+7. `temporaryUnlock()` removes shields for a duration
+8. `DeviceActivityMonitor` extension re-applies shields when the unlock period expires
+
+## Contributing
+
+Contributions are welcome! Please open an issue or PR.
+
+## License
+
+MIT

package/android/build.gradle

@@ -0,0 +1,49 @@
+apply plugin: 'com.android.library'
+apply plugin: 'kotlin-android'
+
+group = 'expo.modules.appblocker'
+version = '0.1.0'
+
+buildscript {
+  def expoModulesCorePlugin = new File(project(":expo-modules-core").projectDir.absolutePath, "ExpoModulesCorePlugin.gradle")
+  if (expoModulesCorePlugin.exists()) {
+    apply from: expoModulesCorePlugin
+    applyKotlinExpoModulesCorePlugin()
+  }
+
+  repositories {
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:2.1.20")
+  }
+}
+
+android {
+  namespace "expo.modules.appblocker"
+
+  compileSdkVersion safeExtGet("compileSdkVersion", 35)
+
+  def agpVersion = com.android.Version.ANDROID_GRADLE_PLUGIN_VERSION
+  if (agpVersion.tokenize('.')[0].toInteger() < 8) {
+    compileOptions {
+      sourceCompatibility JavaVersion.VERSION_17
+      targetCompatibility JavaVersion.VERSION_17
+    }
+
+    kotlinOptions {
+      jvmTarget = JavaVersion.VERSION_17.majorVersion
+    }
+  }
+
+  defaultConfig {
+    minSdkVersion safeExtGet("minSdkVersion", 24)
+    targetSdkVersion safeExtGet("targetSdkVersion", 35)
+  }
+}
+
+dependencies {
+  implementation project(':expo-modules-core')
+  implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk7:2.1.20"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1 @@
+<manifest/>

package/android/src/main/java/expo/modules/appblocker/AppBlockerPrefs.kt

@@ -0,0 +1,21 @@
+package expo.modules.appblocker
+
+import android.content.Context
+import android.content.SharedPreferences
+
+object AppBlockerPrefs {
+  const val PREFS_NAME = "expo_app_blocker_prefs"
+  const val KEY_BLOCKED_PACKAGES = "blocked_packages"
+
+  fun get(context: Context): SharedPreferences =
+    context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+
+  fun getBlockedPackages(context: Context): Set<String> =
+    get(context).getStringSet(KEY_BLOCKED_PACKAGES, emptySet()) ?: emptySet()
+
+  fun setBlockedPackages(context: Context, packages: Collection<String>) {
+    get(context).edit()
+      .putStringSet(KEY_BLOCKED_PACKAGES, packages.toSet())
+      .apply()
+  }
+}

package/android/src/main/java/expo/modules/appblocker/AppBlockerService.kt

@@ -0,0 +1,176 @@
+package expo.modules.appblocker
+
+import android.app.Notification
+import android.app.NotificationChannel
+import android.app.NotificationManager
+import android.app.PendingIntent
+import android.app.Service
+import android.app.usage.UsageEvents
+import android.app.usage.UsageStatsManager
+import android.content.Context
+import android.content.Intent
+import android.net.Uri
+import android.os.Build
+import android.os.Handler
+import android.os.IBinder
+import android.os.Looper
+import android.util.Log
+import androidx.core.app.NotificationCompat
+
+class AppBlockerService : Service() {
+  private val handler = Handler(Looper.getMainLooper())
+  private var lastForegroundPackage: String? = null
+  private lateinit var overlayManager: OverlayManager
+
+  private val pollRunnable = object : Runnable {
+    override fun run() {
+      val foregroundPackage = getCurrentForegroundPackage()
+      if (foregroundPackage != null && foregroundPackage != lastForegroundPackage) {
+        Log.d(TAG, "Foreground changed: $foregroundPackage")
+        lastForegroundPackage = foregroundPackage
+        handleForegroundChange(foregroundPackage)
+      }
+      handler.postDelayed(this, POLL_INTERVAL_MS)
+    }
+  }
+
+  override fun onBind(intent: Intent?): IBinder? = null
+
+  override fun onCreate() {
+    super.onCreate()
+    Log.d(TAG, "AppBlockerService onCreate")
+    overlayManager = OverlayManager(this)
+    createChannelsIfNeeded()
+    startForeground(NOTIFICATION_ID, buildNotification())
+    handler.post(pollRunnable)
+  }
+
+  private fun handleForegroundChange(foregroundPackage: String) {
+    val blocked = AppBlockerPrefs.getBlockedPackages(this)
+    if (foregroundPackage in blocked) {
+      Log.d(TAG, "Blocked app in foreground: $foregroundPackage")
+      overlayManager.show(foregroundPackage)
+      showBlockedNotification(foregroundPackage)
+    } else {
+      overlayManager.hide()
+    }
+  }
+
+  private fun showBlockedNotification(packageName: String) {
+    val appName = try {
+      val pm = this.packageManager
+      val appInfo = pm.getApplicationInfo(packageName, 0)
+      pm.getApplicationLabel(appInfo).toString()
+    } catch (e: Exception) {
+      packageName
+    }
+
+    val scheme = this.packageName.replace(".", "-")
+    val deepLinkIntent = Intent(
+      Intent.ACTION_VIEW,
+      Uri.parse("${scheme}://blocked?app=${Uri.encode(appName)}&package=${Uri.encode(packageName)}")
+    ).apply {
+      addFlags(Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_CLEAR_TOP)
+    }
+
+    val pendingIntent = PendingIntent.getActivity(
+      this, 0, deepLinkIntent,
+      PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
+    )
+
+    val notification = NotificationCompat.Builder(this, BLOCKED_CHANNEL_ID)
+      .setContentTitle("App Blocked")
+      .setContentText("$appName is blocked. Tap to earn free time!")
+      .setSmallIcon(applicationInfo.icon)
+      .setAutoCancel(true)
+      .setPriority(NotificationCompat.PRIORITY_HIGH)
+      .setContentIntent(pendingIntent)
+      .build()
+
+    val manager = getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
+    manager.notify(BLOCKED_NOTIFICATION_ID, notification)
+  }
+
+  override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
+    Log.d(TAG, "AppBlockerService onStartCommand")
+    return START_STICKY
+  }
+
+  override fun onDestroy() {
+    Log.d(TAG, "AppBlockerService onDestroy")
+    handler.removeCallbacks(pollRunnable)
+    overlayManager.hide()
+    super.onDestroy()
+  }
+
+  private fun getCurrentForegroundPackage(): String? {
+    val usageStatsManager =
+      getSystemService(Context.USAGE_STATS_SERVICE) as UsageStatsManager
+    val endTime = System.currentTimeMillis()
+    val beginTime = endTime - LOOKBACK_WINDOW_MS
+    val events = usageStatsManager.queryEvents(beginTime, endTime)
+    val event = UsageEvents.Event()
+    var latestForeground: String? = null
+    while (events.hasNextEvent()) {
+      events.getNextEvent(event)
+      if (event.eventType == UsageEvents.Event.MOVE_TO_FOREGROUND) {
+        latestForeground = event.packageName
+      }
+    }
+    return latestForeground
+  }
+
+  private fun createChannelsIfNeeded() {
+    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+      val manager = getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
+
+      val serviceChannel = NotificationChannel(
+        CHANNEL_ID, "App Blocker", NotificationManager.IMPORTANCE_LOW
+      ).apply {
+        description = "Keeps the app blocker running"
+        setShowBadge(false)
+      }
+      manager.createNotificationChannel(serviceChannel)
+
+      val blockedChannel = NotificationChannel(
+        BLOCKED_CHANNEL_ID, "Blocked App Alerts", NotificationManager.IMPORTANCE_HIGH
+      ).apply {
+        description = "Notifications when a blocked app is detected"
+      }
+      manager.createNotificationChannel(blockedChannel)
+    }
+  }
+
+  private fun buildNotification(): Notification =
+    NotificationCompat.Builder(this, CHANNEL_ID)
+      .setContentTitle("App Blocker")
+      .setContentText("Monitoring blocked apps")
+      .setSmallIcon(applicationInfo.icon)
+      .setOngoing(true)
+      .setPriority(NotificationCompat.PRIORITY_LOW)
+      .build()
+
+  companion object {
+    private const val TAG = "ExpoAppBlocker"
+    private const val CHANNEL_ID = "expo_app_blocker_channel"
+    private const val BLOCKED_CHANNEL_ID = "expo_app_blocker_blocked"
+    private const val NOTIFICATION_ID = 9001
+    private const val BLOCKED_NOTIFICATION_ID = 9002
+    private const val POLL_INTERVAL_MS = 500L
+    private const val LOOKBACK_WINDOW_MS = 10_000L
+
+    fun start(context: Context) {
+      val intent = Intent(context, AppBlockerService::class.java)
+      if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+        context.startForegroundService(intent)
+      } else {
+        context.startService(intent)
+      }
+    }
+
+    fun stop(context: Context) {
+      val intent = Intent(context, AppBlockerService::class.java)
+      context.stopService(intent)
+    }
+  }
+}

package/android/src/main/java/expo/modules/appblocker/BootReceiver.kt

@@ -0,0 +1,19 @@
+package expo.modules.appblocker
+
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+import android.util.Log
+
+class BootReceiver : BroadcastReceiver() {
+  override fun onReceive(context: Context, intent: Intent) {
+    if (intent.action == Intent.ACTION_BOOT_COMPLETED) {
+      Log.d(TAG, "BootReceiver: BOOT_COMPLETED received, starting service")
+      AppBlockerService.start(context.applicationContext)
+    }
+  }
+
+  companion object {
+    private const val TAG = "ExpoAppBlocker"
+  }
+}