c15t/docs/frameworks/javascript/network-blocker.md

Headless JavaScript consent management platform for cookie banners, privacy preferences, consent storage, and script gating.

---
title: Network Blocker
description: Block outgoing network requests to third-party domains until the
  user grants consent for the appropriate category.
group: frameworks
---
The network blocker intercepts outgoing `fetch` and `XMLHttpRequest` calls and blocks them based on consent state and domain rules. This catches tracking requests that happen outside of script loading - for example, beacon calls, API requests to analytics endpoints, or pixel fires from already-loaded scripts.

## Configuration

Add `networkBlocker` to your runtime options:

```ts
import { getOrCreateConsentRuntime } from 'c15t';

const { consentStore } = getOrCreateConsentRuntime({
  mode: 'hosted',
  backendURL: 'https://your-instance.c15t.dev',
  networkBlocker: {
    rules: [
      {
        id: 'google-analytics',
        domain: 'google-analytics.com',
        category: 'measurement',
      },
      {
        id: 'facebook-pixel',
        domain: 'facebook.com',
        pathIncludes: '/tr',
        category: 'marketing',
      },
      {
        id: 'analytics-post',
        domain: 'analytics.example.com',
        methods: ['POST'],
        category: 'measurement',
      },
    ],
  },
});
```

## Rule Matching

Rules match requests using three criteria:

### Domain matching

The `domain` field matches the request hostname. Subdomains are automatically included - a rule for `google-analytics.com` also matches `www.google-analytics.com` and `stats.google-analytics.com`.

### Path matching

The optional `pathIncludes` field requires the request URL path to contain the specified substring. This lets you target specific endpoints without blocking the entire domain.

### Method matching

The optional `methods` array restricts the rule to specific HTTP methods. If omitted, the rule applies to all methods.

## Consent Conditions

Like the script loader, `category` accepts a `HasCondition`:

```tsx
// Simple
{ category: 'measurement' }

// Must have both
{ category: { and: ['measurement', 'marketing'] } }

// Must have either
{ category: { or: ['measurement', 'marketing'] } }
```

## Monitoring Blocked Requests

### Console logging

Blocked requests are logged to the console by default. Disable with `logBlockedRequests: false`.

### Callback

Use `onRequestBlocked` to handle blocked requests programmatically:

```tsx
networkBlocker: {
  rules: [...],
  onRequestBlocked: ({ method, url, rule }) => {
    console.log(`Blocked ${method} ${url} (rule: ${rule?.id})`);
  },
}
```

## Runtime Updates

Update the network blocker configuration at runtime:

```ts
const state = consentStore.getState();

state.setNetworkBlocker({
  rules: [
    {
      id: 'new-tracker',
      domain: 'tracker.example.com',
      category: 'marketing',
    },
  ],
});
```

## API Reference

|Property|Value|
|:--|:--|
|Type Name|\`NetworkBlockerRule\`|
|Source Path|\`./packages/core/src/libs/network-blocker/types.ts\`|

\*ExtractedTypeTable: Could not extract "NetworkBlockerRule" from "./packages/core/src/libs/network-blocker/types.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*

|Property|Value|
|:--|:--|
|Type Name|\`NetworkBlockerConfig\`|
|Source Path|\`./packages/core/src/libs/network-blocker/types.ts\`|

\*ExtractedTypeTable: Could not extract "NetworkBlockerConfig" from "./packages/core/src/libs/network-blocker/types.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*