expo-app-blocker 0.1.43 → 0.1.45

package/.github/workflows/publish.yml

@@ -19,8 +19,13 @@ jobs:
 
       - name: Determine version bump
         id: version
+        # Never inline `${{ github.event.head_commit.message }}` into the
+        # script body — GitHub Actions substitutes it BEFORE the shell runs,
+        # so backticks / parens / `${...}` / `{vars}` get evaluated as
+        # commands. Always pass via env: so it lands as a quoted string.
+        env:
+          COMMIT_MSG: ${{ github.event.head_commit.message }}
         run: |
-          COMMIT_MSG="${{ github.event.head_commit.message }}"
           if echo "$COMMIT_MSG" | grep -qw "\[major\]"; then
             echo "bump=major" >> $GITHUB_OUTPUT
           elif echo "$COMMIT_MSG" | grep -qw "\[minor\]"; then

package/README.md

@@ -86,13 +86,22 @@ npx expo install expo-app-blocker
 
 ### 2. Configure `app.json`
 
+> **Three things are required on iOS** and skipping any of them produces a cryptic build failure:
+> 1. `ios.appleTeamId` — `@bacons/apple-targets` refuses to add the extension targets without it.
+> 2. `ios.entitlements` with **Family Controls + the App Group** — the extension `expo-target.config.js` files read `ios.entitlements['com.apple.security.application-groups'][0]` to learn which App Group to embed. If it's missing they fall back to `group.expo.app-blocker` and the build fails with `An Application Group with Identifier 'group.expo.app-blocker' is not available`.
+> 3. `@bacons/apple-targets` must appear in the `plugins` array **after** `expo-app-blocker`. The targets only get added to the Xcode project when this plugin runs.
+
 ```json
 {
   "expo": {
     "scheme": "myapp",
     "ios": {
       "bundleIdentifier": "com.yourapp.id",
-      "appleTeamId": "YOUR_TEAM_ID"
+      "appleTeamId": "YOUR_TEAM_ID",
+      "entitlements": {
+        "com.apple.developer.family-controls": true,
+        "com.apple.security.application-groups": ["group.com.yourapp.blocker"]
+      }
     },
     "plugins": [
       ["expo-app-blocker", {
@@ -107,12 +116,15 @@ npx expo install expo-app-blocker
             "backgroundBlurStyle": "systemThickMaterialLight"
           }
         }
-      }]
+      }],
+      "@bacons/apple-targets"
     ]
   }
 }
 ```
 
+> The App Group identifier in `ios.entitlements` and `expo-app-blocker.ios.appGroup` **must match** — they describe the same shared-storage container for the main app and the three extensions.
+
 ### 3. Use in your app
 
 ```tsx
@@ -214,6 +226,13 @@ No special setup required beyond what the config plugin handles automatically.
 | `ios.shield.backgroundColor` | `string\|null` | `null` | Solid background color (hex). e.g. `"#f6f6f6"` for light, `"#1a1a2e"` for dark |
 | `ios.shield.backgroundBlurStyle` | `string\|null` | `"systemThickMaterial"` | Blur style. See [Blur Styles](#blur-styles) for all options |
 | `ios.shield.icon` | `string` | SF Symbol | Path to custom shield icon PNG (e.g. `"./assets/shield-icon.png"`) |
+| `ios.shield.tempUnlockTitle` | `string` | `"Almost there!"` | Title shown briefly while ManagedSettings clears after a successful unlock |
+| `ios.shield.tempUnlockSubtitle` | `string` | `"Your free time is loading. Try again in a moment."` | Subtitle for the temporary-unlock state |
+| `ios.shield.tempUnlockButtonLabel` | `string` | `"OK"` | Button label for the temporary-unlock state |
+| `ios.shield.countSuffix` | `string` | `" You have {count} apps blocked."` | Appended to the subtitle when more than one app is blocked. `{count}` is replaced with the integer at runtime. Set to `""` to drop the suffix entirely. |
+| `ios.notification.title` | `string` | `"App Blocker"` | Title of the local notification fired when the user taps the Shield primary button. Set to a Hebrew/Arabic/etc. string to localize. |
+| `ios.notification.body` | `string` | `"Tap to return to the app and complete the unlock challenge."` | Body of the unlock notification |
+| `ios.notification.attachIcon` | `boolean` | `true` | Whether to attach the shield icon as a notification image. Set to `false` to avoid the duplicate-icon look on iOS notification banners (the system app icon is always shown either way). |
 | `android.notificationTitle` | `string` | `"App Blocked"` | Notification title |
 | `android.notificationText` | `string` | `"{appName} is blocked."` | Notification text |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "expo-app-blocker",
-  "version": "0.1.43",
+  "version": "0.1.45",
   "description": "Expo module for cross-platform app blocking. Android: UsageStatsManager + Overlay. iOS: Screen Time API (FamilyControls + ManagedSettings + DeviceActivity).",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/plugin/src/index.js

@@ -285,6 +285,49 @@ function withAppBlockerIOS(config, pluginConfig) {
       const blurRaw = shield.backgroundBlurStyle || (bgColorHex ? null : "systemThickMaterial");
       const blurSwift = blurRaw && blurStyleMap[blurRaw] ? blurStyleMap[blurRaw] : null;
 
+      // Notification config (shown when the user taps the Shield primary button).
+      // All copy is configurable so non-English apps can localize without forking.
+      const notification = pluginConfig?.ios?.notification || {};
+      const notificationTitle = notification.title || "App Blocker";
+      const notificationBody = notification.body || "Tap to return to the app and complete the unlock challenge.";
+      // attachIcon defaults to true to preserve current behavior; set to false
+      // to drop the duplicate icon attachment so only the system app icon shows.
+      const notificationAttachIcon = notification.attachIcon === false ? "false" : "true";
+
+      // Temporary-unlock state copy (shown when the user has just earned time
+      // and the Shield is briefly visible while ManagedSettings clears).
+      const tempUnlockTitle = shield.tempUnlockTitle || "Almost there!";
+      const tempUnlockSubtitle = shield.tempUnlockSubtitle || "Your free time is loading. Try again in a moment.";
+      const tempUnlockButtonLabel = shield.tempUnlockButtonLabel || "OK";
+
+      // "You have N apps blocked" suffix appended to the subtitle when more
+      // than one app is blocked. Set countSuffix to "" to drop it entirely,
+      // or to a localized template like " יש לך {count} אפליקציות חסומות.".
+      // Defaults preserve the legacy English suffix.
+      const countSuffixTemplate = shield.countSuffix !== undefined
+        ? shield.countSuffix
+        : " You have {count} apps blocked.";
+
+      // Swift string-literal escaping. Plugin substitutions land inside `"..."`
+      // literals so backslashes, quotes, and the Swift interpolation escape
+      // `\(` MUST all be escaped or the extension fails to compile.
+      function escapeSwiftString(s) {
+        return String(s)
+          .replace(/\\/g, "\\\\")
+          .replace(/"/g, '\\"')
+          .replace(/\n/g, "\\n")
+          .replace(/\r/g, "\\r");
+      }
+
+      // Render the count suffix template into a Swift expression. We use
+      // `\(count)` interpolation when the template includes `{count}` so the
+      // runtime value is substituted. Empty template → empty literal.
+      function renderCountSuffixSwift(template) {
+        if (!template) return '""';
+        const escaped = escapeSwiftString(template);
+        return `"${escaped.replace(/\{count\}/g, "\\(count)")}"`;
+      }
+
       // All placeholder replacements
       const replacements = {
         "APP_GROUP_PLACEHOLDER": appGroup,
@@ -292,6 +335,13 @@ function withAppBlockerIOS(config, pluginConfig) {
         "SHIELD_SUBTITLE_PLACEHOLDER": shield.subtitle || "{appName} is blocked.",
         "SHIELD_PRIMARY_BUTTON_PLACEHOLDER": shield.primaryButtonLabel || "Earn Free Time",
         "SHIELD_SECONDARY_BUTTON_PLACEHOLDER": shield.secondaryButtonLabel === null ? "none" : (shield.secondaryButtonLabel || "Not now"),
+        "SHIELD_TEMP_UNLOCK_TITLE_PLACEHOLDER": tempUnlockTitle,
+        "SHIELD_TEMP_UNLOCK_SUBTITLE_PLACEHOLDER": tempUnlockSubtitle,
+        "SHIELD_TEMP_UNLOCK_BUTTON_PLACEHOLDER": tempUnlockButtonLabel,
+        "SHIELD_COUNT_SUFFIX_SWIFT_PLACEHOLDER": renderCountSuffixSwift(countSuffixTemplate),
+        "NOTIFICATION_TITLE_PLACEHOLDER": notificationTitle,
+        "NOTIFICATION_BODY_PLACEHOLDER": notificationBody,
+        "NOTIFICATION_ATTACH_ICON_PLACEHOLDER": notificationAttachIcon,
         "SHIELD_PRIMARY_R_PLACEHOLDER": primaryColor.r,
         "SHIELD_PRIMARY_G_PLACEHOLDER": primaryColor.g,
         "SHIELD_PRIMARY_B_PLACEHOLDER": primaryColor.b,

package/targets/ShieldAction/ShieldActionExtension.swift

@@ -7,6 +7,12 @@ class ShieldActionExtension: ShieldActionDelegate {
   private let appGroupIdentifier = "APP_GROUP_PLACEHOLDER"
   private let pendingUnlockKey = "appBlocker.pendingUnlock.v1"
   private let pendingUnlockNotificationIdentifier = "expo.appblocker.pendingUnlock.local"
+  // Notification copy + behavior — configurable via plugin options so apps
+  // can localize without forking. Defaults preserve the original English
+  // copy and the icon attachment.
+  private let notificationTitle = "NOTIFICATION_TITLE_PLACEHOLDER"
+  private let notificationBody = "NOTIFICATION_BODY_PLACEHOLDER"
+  private let notificationAttachIcon = NOTIFICATION_ATTACH_ICON_PLACEHOLDER
 
   override func handle(action: ShieldAction, for application: ApplicationToken, completionHandler: @escaping (ShieldActionResponse) -> Void) {
     handleAction(action, completionHandler: completionHandler)
@@ -67,13 +73,15 @@ class ShieldActionExtension: ShieldActionDelegate {
     let center = UNUserNotificationCenter.current()
 
     let content = UNMutableNotificationContent()
-    content.title = "App Blocker"
-    content.body = "Tap to return to the app and complete the unlock challenge."
+    content.title = notificationTitle
+    content.body = notificationBody
     content.sound = .default
     content.userInfo = ["link": "/unlock"]
 
-    // Attach the app icon to the notification
-    if let iconURL = iconFileURL() {
+    // Attach the app icon to the notification only when the app opted in.
+    // When false the system app icon is the only icon shown — avoids the
+    // "duplicate icon" look on iOS notification banners.
+    if notificationAttachIcon, let iconURL = iconFileURL() {
       if let attachment = try? UNNotificationAttachment(identifier: "icon", url: iconURL, options: nil) {
         content.attachments = [attachment]
       }

package/targets/ShieldConfiguration/ShieldConfigurationExtension.swift

@@ -11,6 +11,11 @@ class ShieldConfigurationExtension: ShieldConfigurationDataSource {
   private let shieldSubtitle = "SHIELD_SUBTITLE_PLACEHOLDER"
   private let shieldPrimaryButtonLabel = "SHIELD_PRIMARY_BUTTON_PLACEHOLDER"
   private let shieldSecondaryButtonLabel = "SHIELD_SECONDARY_BUTTON_PLACEHOLDER"
+  // Temporary-unlock state copy — shown briefly while ManagedSettings clears
+  // after a successful unlock. Configurable via plugin options.
+  private let shieldTempUnlockTitle = "SHIELD_TEMP_UNLOCK_TITLE_PLACEHOLDER"
+  private let shieldTempUnlockSubtitle = "SHIELD_TEMP_UNLOCK_SUBTITLE_PLACEHOLDER"
+  private let shieldTempUnlockButtonLabel = "SHIELD_TEMP_UNLOCK_BUTTON_PLACEHOLDER"
   private let shieldPrimaryButtonColor = UIColor(red: SHIELD_PRIMARY_R_PLACEHOLDER, green: SHIELD_PRIMARY_G_PLACEHOLDER, blue: SHIELD_PRIMARY_B_PLACEHOLDER, alpha: 1.0)
   private let shieldBackgroundColor: UIColor? = SHIELD_BG_COLOR_PLACEHOLDER
   private let shieldBlurStyle: UIBlurEffect.Style? = SHIELD_BLUR_STYLE_PLACEHOLDER
@@ -44,16 +49,18 @@ class ShieldConfigurationExtension: ShieldConfigurationDataSource {
         backgroundBlurStyle: shieldBlurStyle,
         backgroundColor: shieldBackgroundColor,
         icon: mascotIcon,
-        title: ShieldConfiguration.Label(text: "Almost there!", color: shieldTitleColor),
-        subtitle: ShieldConfiguration.Label(text: "Your free time is loading. Try again in a moment.", color: shieldSubtitleColor),
-        primaryButtonLabel: ShieldConfiguration.Label(text: "OK", color: .white),
+        title: ShieldConfiguration.Label(text: shieldTempUnlockTitle, color: shieldTitleColor),
+        subtitle: ShieldConfiguration.Label(text: shieldTempUnlockSubtitle, color: shieldSubtitleColor),
+        primaryButtonLabel: ShieldConfiguration.Label(text: shieldTempUnlockButtonLabel, color: .white),
         primaryButtonBackgroundColor: shieldPrimaryButtonColor,
         secondaryButtonLabel: nil
       )
     }
 
     let count = getBlockedAppCount()
-    let context = count > 1 ? " You have \(count) apps blocked." : ""
+    // The plugin replaces this placeholder with a Swift string literal
+    // containing `\(count)` interpolation, or `""` when the user opted out.
+    let context = count > 1 ? SHIELD_COUNT_SUFFIX_SWIFT_PLACEHOLDER : ""
     let subtitle = shieldSubtitle.replacingOccurrences(of: "{appName}", with: appName) + context
 
     let hasSecondary = !shieldSecondaryButtonLabel.isEmpty && shieldSecondaryButtonLabel != "none"