Blocker

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

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.

---

Architecture Overview

Blocker/
├── source/                  # Source files (your 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 lock enforcement
│   │   ├── DeviceAdmin.kt            # Device Administrator receiver
│   ├── src/                 # React Native UI & Business logic
│   │   ├── screens/         # Screens (HomeScreen, AppBlockerScreen, BlocklistScreen, FocusScreen, SettingsScreen)
│   │   ├── services/        # State management (ProtectionManager, BlocklistEngine)
│   │   ├── hooks/           # Reactive hooks (useProtection)
│   │   ├── native/          # TypeScript bridge definitions (BlockerNative)
│   │   └── data/            # Static data (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
export ANDROID_HOME="$HOME/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, download commandlinetools-linux-*_latest.zip from Google's Android developer portal into ~/Downloads. The build script will automatically detect and extract it into $ANDROID_HOME.

2. Build Commands

Debug Build (Recommended for Testing & Development):

./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:

./build_apk.sh release

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

3. Install on Device

Connect your phone with USB Debugging enabled in Developer Options, then execute:

./05_install_on_phone.sh debug
# or for release:
./05_install_on_phone.sh release

---

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, etc.).
• Component Styling: Edit source/src/ui.tsx for shared components, colors, and glow states.
• Native Android Interception: Edit source/android/AccessibilityService.kt to modify window state detection, URL bar checking, or anti-tamper logic.
• Native Modules & Storage: 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 three Android permissions to function:

1. Accessibility Service: Required to inspect current window activities, detect open URL bars in web browsers, and detect short-form video players (YouTube Shorts, Reels).
2. Display Over Other Apps (Overlay): Used to display the non-intrusive 5-second blocked notification banner.
3. Device Administrator (Optional but recommended): Prevents immediate uninstallation while Protection Mode is active.

---

License & Credits

• Developer: Shell Ninja