Overview
BlockSignal is a fail-open blocker detector and recovery SDK for publishers that need to understand whether monetization resources are being blocked. It reports blocker evidence separately from browser and network health, so CSP restrictions, offline transitions, service-worker interception, and ordinary request failures do not become false ad-block claims.
The default experience is fail-open. A definite blocked result requires healthy environment evidence, strong blocked dominance, and independent failure domains. Hard-wall eligibility remains disabled until labeled blocker-lab data and repeated monetization impact justify it.
Features
- Hosted loader and namespaced browser API contracts
- Script, fetch, frame, and image probes with control pairs
- Explicit blocked, clear, degraded, unknown, and disabled states
- CSP nonce propagation and Trusted Types-aware behavior
- Operational telemetry with sampling, batching, rate limits, and idempotency
- Versioned runtime snapshots, ETags, and immutable loader releases
- Deterministic blocker lab with clean-browser false-positive fixtures
Technology Stack
- TypeScript, React 19, and TanStack Start
- Bun for builds, browser-runtime generation, tests, migrations, and deployment smoke
- PostgreSQL with Drizzle ORM for durable events and configuration
- Vitest and Playwright across unit, component, integration, browser, and blocker-lab suites
- Kubernetes, Flux, and Argo Workflows for deployment
Availability
The repository contains the detector lab, browser runtime, public API routes, and self-hosting configuration. No public BlockSignal service was verified during this audit; use the local demo or deploy the service yourself before embedding a loader.
Links
- Source repository: github.com/briansunter/detect-ad