Blocker v1.0.6.7

Current Version: v1.0.6.7 | Platform: Android 8.0+ (API 26+) | License: Open Source

A privacy-focused, zero-telemetry Android distraction and content blocker built with React Native and native Android Accessibility Services.

Important

Recommendation: Install the Debug Version First!
We strongly recommend installing and testing the Debug version (Blocker-release-debug-{VERSION}.apk) before installing the Release build.

• Test with 1-Minute Timers: The Debug build uses short 1-minute unlock delay timers, allowing you to freely explore, configure your custom blocklists, test focus schedules, and adjust settings without risk of accidentally locking yourself out.
• Upgrade When Ready: Once you have thoroughly tested the app and confirmed everything suits your exact needs, proceed to install the Release version (Blocker-release-{VERSION}.apk), which enforces real 1 to 30 day delayed-unlock timers with strict anti-tamper security and no backdoors.

Warning

Play Protect Warning During Installation
Because Blocker is an open-source, sideloaded app that utilizes Android Accessibility Services and Device Administrator permissions for tamper resistance, Google Play Protect may warn or block installation:

• Quick Install: On the prompt, tap "More details" -> "Install anyway".
• If Blocked: Temporarily disable Play Protect during installation:
  1. Open Google Play Store -> tap your Profile Icon (top right) -> select Play Protect.
  2. Tap the Settings gear in the top right corner.
  3. Turn off "Scan apps with Play Protect".
  4. Install Blocker, then you can turn Play Protect back on once installation finishes.

---

Blocker runs entirely on-device: no remote DNS, no tracking servers, no telemetry, and no account required. It blocks distracting websites, full-screen short-form video players (YouTube Shorts, Instagram Reels, Facebook Reels), and adult domains across browsers and apps.

---

What's New in v1.0.6.7

• Real-Time 1-Second Countdown Ticker & Anti-Tamper Delay Locks:
  • Active delay unlock timers tick down visibly every second (00:59 → 00:58 … → 00:00) driven by a shared, synchronized reactive state engine.
  • Strict countdown delays are enforced across Distraction Shields, Daily Schedule modifications, Focus Mode toggle-off, and Web/Keyword blocklist deletions whenever Protection Mode or Focus Mode is armed.
• Device Admin Smart Allow-Gate:
  • Android's "Device admin apps" list screen can now be browsed and inspected freely. Users can activate and manage other administrator apps (e.g. Find My Device, Google Play Protect) without being kicked to Home.
  • Attempting to deactivate Blocker's Device Administrator remains strictly blocked in 0ms.
• Exact Trigger Reporting in Popups & Floating HUD:
  • Overlay reminders and floating HUD banners now display the exact blocked URL (e.g. Blocked URL: m.example.com / ব্লককৃত লিংক: m.example.com) or restricted keyword phrase (Blocked Keyword: "phrase" / নিষিদ্ধ কীওয়ার্ড: "phrase").
• Soft Keyboard Auto-Scroll & Input Clearance:
  • Configured adjustResize soft input mode and BringIntoViewRequester with IME padding on the Web & Keywords page, ensuring input fields smoothly scroll above the Android keyboard upon focus.
• Default Content Hardening & GitHub Privacy Encryption:
  • Bundled redgifs.com and restricted terms (redgifs, futanari, pawg, erotic) directly into the default binary filtering engine.
  • Full end-to-end repository encryption (encrypted-blocklist and base64 obfuscation) guarantees that no plaintext adult URLs or keywords are exposed when viewing repository files on GitHub.
• Surgical Distraction Ejection & Newsfeed Protection:
  • Passive Facebook Newsfeed scrolling is 100% preserved. Full-screen Reels or video taps trigger an in-app Back action that returns the user straight to the Newsfeed without launcher ejections (GLOBAL_ACTION_HOME).
  • Warning popups are completely silenced during short-form video blocking for a seamless, distraction-free flow.
• Auto-Close & Background Removal on Minimize:
  • Minimized app tasks invoke finishAndRemoveTask(), immediately clearing the app from Android Recents to prevent bypasses via the multitasking overview screen.
• Bilingual Islamic Reminder Dialogs:
  • Reverent Quranic verses and Hadiths available in authentic English and বাংলা, with dedicated language selection in Settings.

---

Core Features

• Pomodoro Study Mode (Full Phone Lockdown): Seamlessly integrated into the Focus page with a segmented switcher.
  • Customizable Cycles: Set study focus intervals (15m to 180m), rest breaks (3m to 15m), and session rounds (1 to 6).
  • Aggressive Phone Lockdown: All apps, home launcher, settings, and navigation are blocked during study sessions, returning directly to the running study timer within milliseconds.
  • Quick Settings & Status Bar Shield: Automatically collapses notification shade pulls (StatusBarManager.collapsePanels()), preventing unauthorized toggling of Wi-Fi, mobile data, or airplane mode.
  • Complete Silencing & Do Not Disturb: Automatically activates Do Not Disturb (INTERRUPTION_FILTER_NONE) and zeroes ringtone, media, notification, and system volume streams, cleanly restoring prior volumes upon completion.
  • Interactive Wi-Fi Controls: Monitor Wi-Fi status and toggle network connectivity on demand directly within Blocker without breaking lockdown.
  • Display Standby Friendly: Safely turn off the screen using the physical power button; unlocking returns straight to the active timer.
  • Emergency Safeguard: Dialer and emergency telecom services are explicitly whitelisted for critical safety.
• Anti-Tamper & Clock Manipulation Defense:
  • Date & Time Tamper Shield: Dual-layer protection (instant window interception + continuous screen text scanner) prevents users from manipulating device date/time in Android Settings to prematurely expire delayed unlock timers.
  • System Settings Guard: Strictly blocks access to Developer Options, Device Administrator settings, and App Info / Force Stop / Uninstall screens.
  • Debugging Lockdown: Automatically detects and disables USB and Wireless debugging if enabled.
• Hardened Content & Distraction Shields:
  • URL User-Info Domain Spoofing Defense: Hardened domain extraction parser (hostOf) strips user credentials (user@host) and decodes percent-encoded characters, eliminating bypasses like https://safe.org@blocked-domain.com.
  • Granular Distraction Shields: Independent toggles for YouTube Shorts, Instagram Reels, and Facebook Reels without breaking main app feeds.
  • Offline Content Database: Fast, local, obfuscated adult domain database with custom domain blocklists and keyword whitelisting.
• In-App Updater & Security Verification:
  • Automated Update Checks: Checks for official GitHub releases on an active 2-hour cycle (with 24-hour backoff if an update is pending) with in-app changelog viewer and direct APK installer.
  • Package Identity Verification: Enforces strict package name validation (pi.packageName == rc.packageName) before invoking Android package installer on downloaded APKs.
  • URL Sanitization: Release links are strictly validated against official GitHub repositories.
  • Automatic Storage Cleanup: Purges cached APK files immediately upon successful installation.
• Delayed Unlock Timers: Any attempt to weaken protections, unblock apps, or shorten timers requires waiting out an unbreakable delay of 24 hours to 30 days.

---

Screenshots

Home Live blocking stats, master toggle, and permission health check.	Focus Mode Instant distraction-free sessions with preset or custom timers.	Study Mode (Lockdown) Aggressive phone lockdown, custom intervals, DND, and quick settings shield.
Daily Schedules Automate recurring focus blocks with precise time pickers.	Distraction Shields Exit YouTube Shorts, Instagram Reels, and Facebook video feeds automatically.	Apps & Scans Block installed apps outright or exempt safe apps from screen scanning.
Usage Limits Enforce maximum daily screen time per app protected by delay locks.	Web & Keywords Adult domain database, custom domain blocklist, and keyword whitelisting.	Settings & Shield Uninstall shield, wireless debugging locks, and 1-30 day delay timers.
In-App Updater Automated 2-hour update checks, in-app changelog viewer, and direct APK installation.

---

Architecture Overview

Blocker/
├── source/                  # Source files (working directory)
│   ├── App.tsx              # Main entry point and bottom tab navigation
│   ├── android/             # Native Kotlin code
│   │   ├── AccessibilityService.kt   # System-wide window tracker & content interceptor
│   │   ├── BlockerNativeModule.kt    # React Native bridge, delay locks & APK updater
│   │   ├── DeviceAdmin.kt            # Device Administrator receiver
│   ├── src/                 # React Native UI & Business logic
│   │   ├── screens/         # Screens (HomeScreen, AppBlockerScreen, BlocklistScreen, FocusScreen, SettingsScreen, UpdateModal)
│   │   ├── services/        # State management (ProtectionManager, BlocklistEngine, UpdateService)
│   │   ├── hooks/           # Reactive hooks (useProtection, useAppUpdate)
│   │   ├── native/          # TypeScript bridge definitions (BlockerNative)
│   │   └── data/            # Static data (appVersion, categories, userLists)
├── blocklists/              # Blocklist source files
│   ├── block-list.md        # Obfuscated adult domain, keyword, and TLD database
│   ├── my_list.txt          # Plaintext user additions (1 per line)
│   └── whitelist.txt        # Plaintext whitelist entries (1 per line)
├── assets/                  # App icon source artwork (app-icon-source.png)
├── build_apk.sh             # Main automated build script
├── 05_install_on_phone.sh   # ADB install script for connected device
├── import_lists.py          # Blocklist parser & userLists generator
├── patch_android.py         # Copies source into React Native project and patches Android files
├── set_version.py           # Auto-increments version and build numbers
└── env.sh                   # Environment variables (Android SDK, Java paths)

---

Prerequisites & Required Packages

Building Blocker requires:

1. Operating System: Linux (Arch Linux recommended; Debian/Ubuntu supported with equivalent packages)
2. Java Development Kit: JDK 17 (OpenJDK 17)
3. Node.js: Node.js LTS (v18 or v20) and npm
4. Android SDK & Build Tools:
   • Android SDK Platform 34 (platforms;android-34)
   • Build Tools 34.0.0 (build-tools;34.0.0)
   • NDK 25.1.8937393 (ndk;25.1.8937393)
   • CMake 3.22.1 (cmake;3.22.1)
   • Android Command-Line Tools (cmdline-tools;latest)
   • Android Platform Tools (adb)
5. Python: Python 3.8+ with standard library (used by build helper scripts)
6. System Utilities: git, unzip, bash

Package Installation Commands

Arch Linux:

sudo pacman -S --needed jdk17-openjdk nodejs npm android-tools unzip git python
sudo archlinux-java set java-17-openjdk

Ubuntu / Debian:

sudo apt update
sudo apt install -y openjdk-17-jdk nodejs npm adb unzip git python3
sudo update-alternatives --set java /usr/lib/jvm/java-17-openjdk-amd64/bin/java

---

Building the APK

The primary build pipeline is controlled by build_apk.sh.

1. Configure Environment (env.sh)

Ensure env.sh points to your installed Android SDK and Java 17 locations:

export JAVA_HOME=/usr/lib/jvm/java-17-openjdk

HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
export ANDROID_HOME="$HERE/Android/Sdk"
export ANDROID_SDK_ROOT="$ANDROID_HOME"
export PATH="$JAVA_HOME/bin:$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/platform-tools:$PATH"

If you do not have the Android SDK command-line tools yet, place commandlinetools-linux-*_latest.zip directly in the Blocker-App directory (or ~/Downloads). You can also place android-ndk-r25b-linux.zip and gradle-8.3-all.zip in Blocker-App to skip large downloads over the network. The build script automatically detects and sets them up.

2. Build Commands

Debug Build (Recommended First Step):

./build_apk.sh debug

• Uses 1-minute delay timers for protection unlocks so you do not get locked out while testing.
• Automatically imports blocklists, increments the build number, patches React Native files, and compiles.
• Outputs the binary to: apk/Blocker-debug-{build_number}.apk.

Release Build (When Ready for Real Protection):

./build_apk.sh release

• Enforces real 1 to 30 day delayed-unlock timers.
• Strict anti-tamper security: settings changes cannot be bypassed without waiting the full duration.
• Outputs the binary to: apk/Blocker-release-{build_number}.apk.

3. Install on Device

Direct APK Sideloading (Phone):

1. Copy or download the compiled APK to your Android device.
2. Open the file to start installation.
3. If Google Play Protect blocks the install:
   • Tap "More details" -> "Install anyway".
   • If blocked completely, open Google Play Store -> tap your Profile (top right) -> Play Protect -> tap Settings -> temporarily turn off "Scan apps with Play Protect" while installing. You can turn it back on after installation.

---

How to Modify and Customize

1. Editing App Logic & UI

All application development takes place under the source/ folder:

• UI Screens: Edit source/src/screens/ (HomeScreen.tsx, SettingsScreen.tsx, FocusScreen.tsx, UpdateModal.tsx, etc.).
• Component Styling: Edit source/src/ui.tsx for shared components, colors, and design system.
• Native Android Interception: Edit source/android/AccessibilityService.kt to modify window state detection, URL bar checking, or anti-tamper logic.
• Native Modules & Updater: Edit source/android/BlockerNativeModule.kt to modify Kotlin methods exposed to React Native.

Important: Do not edit directly inside project/ (or $BLOCKER_DIR) - that directory is the build target. Always edit inside source/. The build script copies files from source/ into project/ (or $BLOCKER_DIR) automatically during the build process.

To manually sync changes from source/ into the build target without a full rebuild:

python3 patch_android.py ~/Blocker source

2. Adding or Modifying Blocklists

• Custom Additions: Open blocklists/my_list.txt and add one domain or keyword per line.
• Whitelist Items: Open blocklists/whitelist.txt and add entries (e.g., words like camera or essex that contain false-positive substrings).
• After updating text lists, regenerate the TypeScript database:

  python3 import_lists.py

3. Changing the App Icon

• Replace assets/app-icon-source.png with your desired PNG image (recommended 1024x1024).
• Regenerate all Android mipmap icon resolutions:

  python3 generate_icons.py
  python3 embed_icon.py

---

Required Android Permissions

Once installed on a physical device, Blocker requires the following permissions to provide full protection:

1. Accessibility Service: Required to inspect active window activities, detect open URL bars in web browsers, scan text for blocked keywords, detect short-form video players (YouTube Shorts, Reels), and enforce Study Mode phone lockdown.
2. Display Over Other Apps (Overlay): Used to display the non-intrusive blocked notification banner and reminder screen.
3. Usage Access (Package Usage Stats): Required to calculate daily per-app usage time and enforce daily app limits.
4. Device Administrator: Prevents immediate uninstallation while Protection Mode is active.
5. (Optional) Do Not Disturb (Notification Policy Access): Allows Pomodoro Study Mode to automatically suppress all notifications, alerts, and ringtones during focus sessions.
6. (Optional) Write Secure Settings: Allows Blocker to automatically and instantly turn off USB & Wireless debugging if enabled (adb shell pm grant com.blocker android.permission.WRITE_SECURE_SETTINGS).

---

Detailed Release History

For complete release notes, changelogs, and historical version details, see RELEASE_NOTES.md.

---

License & Credits

• Developer: Shell Ninja