Skip to content

About

initial commit

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

LinkScrub 🧼

LinkScrub App Icon

Clean, Private, and Intelligent URL Sanitizer for Android
Strip tracking parameters, unshorten redirect hops, preview link metadata, and share cleanly β€” 100% on-device.

Android CI Kotlin Version Jetpack Compose Material Design 3 Android Version Get it on Google Play License Adaptive Ready Privacy First

Get it on Google Play


πŸ“– Overview

In modern internet browsing, URLs shared across social platforms, messaging apps, and email newsletters are heavily contaminated with tracking identifiers (utm_*, fbclid, gclid, gbraid, igsh, TikTok telemetry, Amazon session tags, and affiliate redirections). These tokens compromise user privacy by correlating identity across websites, bloating URLs into unreadable walls of text, and masking target destinations through shortener redirects (bit.ly, t.co, etc.).

LinkScrub is an open-source, privacy-first Android utility inspired by projects like Leon and Felis. It intercepts, de-obfuscates, cleans, and previews URLs with full transparency:

  • No telemetry, zero cloud tracking, 100% local processing.
  • Fine-grained parameter control with domain-aware rule preservation (such as preserving YouTube timestamps).
  • Network unshortening with cycle loop guards.
  • Rich Open Graph previews without browser bloat.

✨ Key Features

1. πŸ§™ Guided 3-Step URL Sanitization Flow

A smooth, animated wizard guides users step-by-step:

  1. Input: Paste raw text or URL via quick paste button, clipboard auto-detection, or intent interception.
  2. Review & Scrub: Inspect individual query parameters grouped by category (Tracking tokens highlighted vs. Safe query params). Toggle parameters on/off with interactive FilterChips before committing.
  3. Preview & Share: Inspect the clean destination URL, Open Graph card, and copy or dispatch immediately to other apps via the system share sheet.

2. ⚑ Quick-Clean Mode

Need fast scrubbing without extra taps?

  • One-tap auto-clean action that sanitizes the URL and copies it straight to your clipboard with haptic feedback.
  • Configurable auto-copy options for rapid link sharing workflows.

3. 🎯 Intelligent Parameter Stripping & Domain-Aware Rules

  • Comprehensive Tracking Catalog: Built-in rules strip UTM parameters (utm_source, utm_campaign, etc.), Google Ads (gclid, wbraid, gbraid, dclid, gad_source), Meta/Facebook/Instagram (fbclid, igsh, igshid), Twitter/X (twclid, s, t), TikTok/ByteDance (_t, _r, tt_from), Hubspot, Matomo, and general affiliate click markers.
  • Domain-Aware Intelligence:
    • YouTube / YouTube Shorts / youtu.be: Preserves the video playback timestamp (t=...) while stripping tracking markers like si and feature.
    • Amazon: Cleans deep path-based referral links (/ref=...) and session tags (pf_rd_*, pd_rd_*, tag) while preserving core ASIN product paths.
    • Regex Fallbacks & Wildcards: Matches custom tracking prefixes (utm_*, itm_*, at_*, vero_*).

4. πŸ”— HTTP Redirect Unshortener & Cyclic Loop Protection

  • Resolves shortened links (bit.ly, t.co, tinyurl.com, etc.) up to configurable hops.
  • Efficiently queries endpoints using lightweight HEAD requests with automatic graceful fallback to streaming GET.
  • Cyclic Loop Detection: Tracks visited redirect nodes to prevent infinite redirection loops and denial-of-service traps.

5. πŸ–ΌοΈ Rich Open Graph & Twitter Card Preview

  • Extracts Open Graph (og:title, og:description, og:image, og:site_name) and Twitter Card metadata using Jsoup.
  • Memory-efficient streaming with Coil Compose image rendering, shimmer placeholder animations, and error fallbacks.
  • Verified destination preview so you can preview where a link leads before opening it in a browser.

6. πŸ“² Android System Integration & Intent Interception

  • Share Sheet Receiver (ACTION_SEND): Select LinkScrub from any app's share menu (WhatsApp, Slack, Telegram, Twitter, Chrome) to clean links in-place.
  • Browser Interception (ACTION_VIEW): Optionally set LinkScrub as a handler for HTTP/HTTPS links to scrub URLs automatically before opening your browser.
  • Text-in-Bulk Extraction: Regex-based URL parser extracts and scrubs URLs embedded inside longer conversational text blocks.

7. πŸ“± Material Design 3 Adaptive Dual-Pane Layout

  • Powered by Material 3 Expressive and androidx.compose.material3.adaptive.layout.SupportingPaneScaffold.
  • Phone (Compact): Focused, ergonomic single-pane layout with bottom-sheet access to history and smooth horizontal step transitions.
  • Foldables & Tablets (Expanded / Dual-Pane): 50:50 side-by-side split pane with live scrubber controls on the primary pane and searchable local history on the supporting pane.
  • Full Edge-to-Edge display with predictive navigation, dynamic wallpaper color theming (Android 12+), and contrast accessibility.

8. πŸ—„οΈ Local History & Search

  • Backed by Room Database (SQLite) with zero cloud sync.
  • Search past cleaned links by URL, domain, or title.
  • One-tap re-copy, re-clean, or clear history anytime.

πŸ›οΈ Architecture & Tech Stack

LinkScrub is engineered following modern Android development practices, MVVM architecture, and Unidirectional Data Flow (UDF).

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚                        UI Layer                             β”‚
β”‚  Jetpack Compose + Material 3 Expressive + Adaptive Scaffold β”‚
β”‚          LinkScrubScreen  ◄──►  LinkScrubViewModel          β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–²β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                               β”‚ UI State / User Intents
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚                       Domain Layer                          β”‚
β”‚        CleanUrlUseCase        β”‚         UrlCleaner          β”‚
β”‚   (Domain-Aware Rules, Parameter Blocklists, Text Parser)   β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–²β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                               β”‚
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚                        Data Layer                           β”‚
β”‚   OkHttpRedirectUnshortener   β”‚      OpenGraphScraper       β”‚
β”‚      (Redirect Resolution)    β”‚    (Jsoup Metadata Scraper) β”‚
β”‚               HistoryRepository & Room Database             β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
Component Technology Role
Language Kotlin 2.0.21 Modern concise, type-safe development
UI Framework Jetpack Compose Declarative UI toolkit
Design System Material Design 3 (M3 Expressive) Modern shapes, dynamic colors, elevation, and typography
Adaptive Layouts androidx.compose.material3.adaptive Responsive dual-pane layouts for foldables & tablets
Concurrency Kotlin Coroutines & StateFlow Asynchronous, reactive state management
Local Storage Room Offline-first SQLite persistence for cleaned links
Networking OkHttp High-performance redirect unshortening & HTTP queries
HTML Parsing Jsoup Robust, memory-safe Open Graph & Twitter Card metadata extraction
Image Loading Coil Compose Asynchronous image loading for link previews

πŸ”’ Privacy Commitment

LinkScrub is built on one foundational principle: your data belongs exclusively to you.

  • 0% Analytics / 0% Telemetry: No Firebase Analytics, No Mixpanel, No Sentry, No advertising SDKs.
  • 100% On-Device Processing: Link stripping and regular expressions run entirely on your CPU.
  • Transparent Network Requests: The network is accessed solely when:
    1. Resolving a redirect chain (HTTP HEAD/GET to the URL target).
    2. Fetching Open Graph metadata (HTML GET and image thumbnail).
  • No Remote Database: Cleaning history is saved locally in a private SQLite database via Room and never leaves your device. You can purge history at any moment with a single tap.

πŸš€ Getting Started & Building

Prerequisites

  • Android Studio: Android Studio Ladybug (2024.2.1+) or Meerkat (2024.3.1+)
  • JDK: Java Development Kit 17 or higher
  • Android SDK: Compile SDK 35 / 37, Min SDK 28 (Android 9.0+)

Clone the Repository

git clone https://github.com/<your-username>/LinkScrub.git
cd LinkScrub

Build & Run via Gradle

  • Build Debug APK:

    ./gradlew assembleDebug
    
  • Run Unit Tests:

    ./gradlew testDebugUnitTest
    
  • Run Instrumented UI & Device Tests:

    ./gradlew connectedDebugAndroidTest
    

πŸ§ͺ Testing

The project maintains comprehensive test coverage across all layers:

  • Unit Tests:
    • UrlCleanerTest: Validates stripping of UTM tags, Google Ads, TikTok, Meta parameters, and domain-specific rules (e.g., YouTube timestamp retention, Amazon clean paths).
    • CleanUrlUseCaseTest: Validates end-to-end clean execution.
    • RedirectUnshortenerTest: Validates redirection hop tracking and cyclic loop termination.
    • OpenGraphScraperTest: Tests robust HTML parsing of Open Graph and Twitter Card tags.
    • LinkScrubViewModelTest: Tests UDF state transitions across Wizard steps.
  • Instrumentation & UI Tests:
    • LinkScrubUiTest: End-to-end Compose UI test verifying wizard interactions, chips, and responsive behavior.

🀝 Contributing

Contributions to LinkScrub are welcome!

  1. Fork the Project.
  2. Create your Feature Branch (git checkout -b feature/NewTrackingRule).
  3. Commit your Changes (git commit -m 'Add tracking rule for NewService').
  4. Push to the Branch (git push origin feature/NewTrackingRule).
  5. Open a Pull Request.

Please ensure all tests pass (./gradlew testDebugUnitTest) before submitting a PR.


πŸ“„ License

LinkScrub is distributed under the GNU General Public License v3.0 (GPLv3). See the LICENSE.md file for more information.

Copyright (C) 2026 Fung Lam

LinkScrub is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program. If not, see <https://www.gnu.org/licenses/>.

About

initial commit

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Releases

Sponsor this project

Packages

Contributors

Languages