Interventions

Configure intervention reporting to detect when browsers automatically block heavy ads, throttle slow scripts, or override your code to protect users — giving you visibility into actions that would otherwise be completely invisible.

New to intervention monitoring? Read our Interventions overview to understand the benefits before diving into configuration.

What are Browser Interventions?

Browser interventions are automatic actions that browsers take to protect users from bad experiences. Unlike deprecation warnings (which just log a message), interventions actively change or block behavior — removing an ad that uses too much CPU, muting a video that tries to auto-play, or blocking a script that would slow down page load.

When an intervention occurs, your code doesn't throw an error — the browser simply doesn't do what you asked. The user might see "Ad removed" where an ad should be, or a video that won't play, or a script that silently fails to load. Without intervention reporting, you'd have no idea anything went wrong.

Intervention reports are sent automatically to your default endpoint, just like deprecation reports. Each report includes an id identifying the intervention type, a human-readable message, and source location information to help you track down the problematic code.

Specification

• WICG Intervention Reporting — Official specification
• MDN: InterventionReportBody — API reference
• WICG Interventions Repository — Historical discussions and intervention list

Browser Support

Intervention reporting has ~80% global browser support, covering Chromium-based browsers.

Why Monitor Interventions?

Intervention reports reveal problems that are completely invisible to traditional monitoring:

• Revenue protection — Every blocked heavy ad is lost ad revenue. Know immediately when ads are being removed so you can fix or replace problematic creatives.
• User experience visibility — Auto-play blocks, throttled scripts, and removed content all affect UX, but your backend sees a "successful" page load.
• Third-party accountability — Identify which ad networks, video players, or analytics scripts trigger interventions on your pages.
• Performance insights — Intervention reports tell you exactly which resources exceeded browser thresholds, guiding optimization efforts.
• Proactive debugging — Find out about blocked content from reports, not from user complaints or revenue drops.

Who Benefits

• AdOps teams — Monitor ad creative performance and catch heavy ads before they drain revenue
• Performance engineers — Identify resource-intensive scripts that trigger browser throttling
• Frontend architects — Track which third-party integrations cause intervention issues
• Publishers — Protect ad inventory by detecting and replacing blocked creatives

When to Enable

Intervention reporting is recommended for all production websites, but it's essential for ad-supported sites. Chrome's Heavy Ad Intervention alone affects approximately 0.3% of ads — but those ads account for 27% of all ad network data usage. If you run ads, you need this visibility.

For non-ad-supported sites, intervention reports still provide value by catching throttled scripts, blocked auto-play media, and other browser overrides that could affect user experience.

How to Configure

Step 1: Set Up the Reporting Endpoint

Define where browsers should send reports using the Reporting-Endpoints header:

Reporting-Endpoints: default="https://reporting-api.app/browser-reports/YOUR-ENDPOINT-UUID"

Replace YOUR-ENDPOINT-UUID with your application's unique endpoint from the reporting-api.app dashboard.

Step 2: That's It!

There's no additional configuration required. Once the Reporting-Endpoints header is in place, browsers will automatically send intervention reports to your default endpoint whenever they block or modify behavior on your pages.

Why so simple? Intervention reports, like deprecation reports, are always sent to the default endpoint group — there's no way to override this behavior. The browser decides what constitutes an intervention.

Step 3: Monitor Reports

After deploying the header, intervention reports will start flowing automatically. Monitor incoming reports in your dashboard for:

• Heavy ad interventions — Ads removed for exceeding CPU or network thresholds
• Script throttling — Scripts blocked or delayed due to performance concerns
• Auto-play blocks — Media that was prevented from auto-playing
• Document.write blocks — Scripts blocked on slow connections

Step 4: Set Up Integrations

Route intervention reports to your existing tools for alerting and analysis:

• AppSignal integration — Track interventions alongside application errors
• Webhook integration — Send reports to Slack, custom dashboards, or ad monitoring systems
• Google Chat integration — Post alerts to team chat spaces

See the Integrations documentation for setup instructions.

Understanding Intervention Reports

When browsers intervene on your behalf, they send JSON reports explaining what happened. Understanding these fields helps you identify and fix the root cause.

Report Fields

Example Report

{
  "type": "intervention",
  "age": 0,
  "url": "https://example.com/article",
  "body": {
    "id": "HeavyAdIntervention",
    "message": "Ad was removed because its CPU usage exceeded the limit.",
    "sourceFile": "https://ads.example.net/creative/12345.js",
    "lineNumber": null,
    "columnNumber": null
  }
}

Common Intervention Types

Here are the most frequently encountered intervention types and what triggers them:

For a complete list of interventions, see the WICG Interventions repository.

Heavy Ad Intervention Thresholds

Chrome's Heavy Ad Intervention is the most impactful for publishers. Chrome removes ads that exceed any of these thresholds before user interaction:

Revenue Impact

While only 0.3% of ads trigger heavy ad intervention, these problematic ads have an outsized impact:

• Heavy ads account for 27% of all ad network data usage
• Heavy ads consume 28% of all ad CPU time
• 86% of blocked heavy ads are video ads — often premium inventory

Monitoring intervention reports lets you identify and replace these problematic creatives before they cost you more revenue.

Preventing Interventions

The best way to handle interventions is to prevent them. Here are strategies for common intervention types:

Heavy Ad Prevention

• Optimize video encoding — Video ads are the most common heavy ad offenders. Use efficient codecs and appropriate bitrates.
• Lazy-load resources — Don't load all creative assets upfront; wait until the ad is visible.
• Minimize JavaScript — Reduce CPU usage by minimizing script execution in ad creatives.
• Test with throttling — Use Chrome DevTools to simulate slow CPUs and verify ads stay under thresholds.
• Monitor creative sizes — Stay well under 4MB total for all ad resources.

Document.write Prevention

• Use async/defer — Load scripts asynchronously instead of using document.write().
• Dynamic script injection — Create script elements programmatically and append to DOM.
• Update legacy ad tags — Many document.write() issues come from outdated ad tag implementations.

Testing for Interventions

To test heavy ad detection specifically, use Chrome flags:

1. Navigate to chrome://flags/#heavy-ad-privacy-mitigations
2. Set to "Disabled" to remove random noise from threshold detection
3. Use Chrome DevTools Performance panel to measure CPU usage
4. Use DevTools Rendering panel → "Highlight Ad Frames" to verify ad detection

You can also test sample heavy ads at heavy-ads.glitch.me.

Server Configuration Examples

Nginx

server {
    # ... your existing configuration ...

    # Reporting endpoint for all report types including interventions
    add_header Reporting-Endpoints 'default="https://reporting-api.app/browser-reports/YOUR-UUID"' always;
}

Ruby on Rails

# Add Reporting-Endpoints header for intervention and other reports
# Note: Use lowercase header names for Rack 3 compatibility
config.action_dispatch.default_headers.merge!(
  "reporting-endpoints" => 'default="https://reporting-api.app/browser-reports/YOUR-UUID"'
)

Apache

Header always set Reporting-Endpoints 'default="https://reporting-api.app/browser-reports/YOUR-UUID"'

Troubleshooting

Reports Not Appearing

• Check browser support — Intervention reports only work in Chromium-based browsers (Chrome, Edge, Opera). Firefox and Safari do not support this feature.
• Verify headers are sent — Use browser DevTools (Network tab) to confirm the Reporting-Endpoints header is present in responses.
• Check allowed origins — Ensure your website's origin is whitelisted in your application settings.
• Trigger an intervention — Test with a known heavy ad or use the DevTools to simulate intervention conditions.

Identifying Intervention Sources

• Check sourceFile — The sourceFile field often identifies the script or resource that triggered the intervention.
• Group by ad network — If multiple heavy ad interventions come from the same ad domain, contact that network.
• Correlate with ad server — Match intervention timestamps with your ad server logs to identify specific creatives.

High Report Volume

• Focus on heavy ads first — HeavyAdIntervention has direct revenue impact; prioritize these.
• Group by id — Aggregate reports by intervention type to identify patterns.
• Filter by your domain vs. third-party — Separate your code issues from vendor issues.

Next Steps

• Crash Reports — Detect browser and tab crashes that destroy your JavaScript
• Integrations — Route reports to your observability tools
• Getting Started — Set up your first application