Skip to content

Debloat any Android or Google TV over Wi-Fi and get an Apple TV-style home.

4.0 KB
Raw Blame

Ad Blocking

Your network's ad blocker on the TV: today's queries, how many were blocked and the share, from Pi-hole (version 6, or version 5) or AdGuard Home, and one OK to pause blocking for five minutes when a site or app won't work. A community add-on, not made by or affiliated with either project. For the Clean Your TV launcher it declares a module card: once you answer Show card its tile reads "Ad Blocking" with a red glow. On any other Android TV home it is an ordinary app.

Ad Blocking on a TV, with demo data

Row What it does
Blocking On or Paused. OK pauses blocking for 5 minutes, or turns it back on.
Queries today, Blocked today, Blocked share The server's own counters.
Blocker Pi-hole or AdGuard Home; OK switches.
Address, Username (AdGuard Home), Password The connection.

It reads the server every 30 seconds while the screen is open, and nothing when it is closed.

How it talks to each server

  • Pi-hole 6: POST /api/auth with the password (or an app password, needed when two-factor login is on), then GET /api/stats/summary and GET /api/dns/blocking with the session id, POST /api/dns/blocking to pause, and DELETE /api/auth at the end of every round, so it never holds one of Pi-hole's limited sessions. A Pi-hole without a password needs none.
  • Pi-hole 5 (when /api/auth isn't there): /admin/api.php?summaryRaw&auth=<API token>, and disable=300 or enable to pause. The API token is under Settings, API in Pi-hole's web page.
  • AdGuard Home: GET /control/stats and GET /control/status with HTTP basic authentication, and POST /control/protection to pause.

Setup

Open the app and fill in the address and login with the TV's keyboard, or push them from a computer as a file so the password is never typed on the TV or put on a command line:

echo '{"kind": "pihole", "url": "http://192.168.1.2", "password": "..."}' > backup/ad-blocking.json
# AdGuard Home: {"kind": "adguard", "url": "http://192.168.1.2:3000", "user": "admin", "password": "..."}
TV_HOST=<tv ip> addons/ad-blocking/install.sh backup/ad-blocking.json

The app takes the file into its own storage and deletes it. Keep the file outside the repo (backup/ is git-ignored).

Permissions

Permission Why
INTERNET Your Pi-hole or AdGuard Home, and nothing else: no telemetry, no update checks, no ads.

Plain http:// is allowed for the home network (res/xml/network.xml). The password stays in the app's own storage (backups are off) and is sent only to the address you entered. ConfigProvider takes a pushed file and only the ADB shell can use it (it requires WRITE_SECURE_SETTINGS). No background service, accounts or libraries.

Build and install

JDK 17 and Android SDK platform 34 with build-tools 34.0.0, as for the launcher:

TV_HOST=<tv ip> addons/ad-blocking/install.sh [config.json]

To build only: cd addons/ad-blocking && ./gradlew assembleRelease; the JVM tests run with ./gradlew testReleaseUnitTest.

Limits

  • Self-signed HTTPS certificates are refused. Use http:// on the home network.
  • Today is the server's own window: Pi-hole counts the last 24 hours, AdGuard Home its statistics period.

Tested on

MOKA R8G (Android 14), on a home app that implements the module-card spec, against a stand-in Pi-hole 6 on the home network answering with the documented response shapes: the config pushed through ConfigProvider, login, the numbers, pause and resume, and the session closed after each round. Not yet tried against a real Pi-hole or AdGuard Home: the author has neither; reports are welcome. Pi-hole 5 and AdGuard Home are covered by JVM tests against their documented responses and local stand-ins. The screenshot shows that demo data, with the address blurred.

Maintainer

@maxhayim