Script Blocking

How It Works

Zest uses a sophisticated script blocking system that:

1. Monitors the DOM using MutationObserver to detect new scripts
2. Checks each script against blocking rules based on the configured mode
3. Blocks matching scripts by changing their type to text/plain
4. Queues blocked scripts for later execution
5. Replays scripts when the user grants consent

Blocking Modes

Manual Mode

Only blocks scripts explicitly tagged with data-consent-category:

<!-- This will be blocked -->
<script data-consent-category="analytics" src="https://example.com/tracker.js"></script>

<!-- This will NOT be blocked -->
<script src="https://www.googletagmanager.com/gtag/js"></script>

Safe Mode (Default)

Blocks manually tagged scripts plus known major trackers:

Blocked Analytics:

• google-analytics.com
• analytics.google.com
• googletagmanager.com
• plausible.io
• cloudflareinsights.com

Blocked Marketing:

• connect.facebook.net
• ads.google.com
• googleads.g.doubleclick.net
• pagead2.googlesyndication.com

Strict Mode

Everything in Safe mode plus extended tracking services:

• Hotjar, Microsoft Clarity, Heap
• Mixpanel, Segment, FullStory, Amplitude
• LinkedIn, Twitter/X, TikTok, Snapchat, Pinterest
• Bing, Yahoo, Amazon, Criteo, Taboola, Outbrain

Doomsday Mode

Blocks all third-party scripts. Use with caution—this may break legitimate functionality.

Tagging Scripts

Basic Tagging

Use data-consent-category to specify which consent category a script requires:

<!-- Requires analytics consent -->
<script data-consent-category="analytics" src="https://example.com/analytics.js"></script>

<!-- Requires marketing consent -->
<script data-consent-category="marketing" src="https://example.com/pixel.js"></script>

<!-- Inline scripts work too -->
<script data-consent-category="analytics">
  console.log('This runs after analytics consent');
</script>

Categories

Category	Purpose
essential	Always allowed (cannot be blocked)
functional	Site personalization features
analytics	Usage tracking and statistics
marketing	Advertising and remarketing

Allow-listing Scripts

Prevent a script from being blocked (even in strict/doomsday mode):

<script data-zest-allow src="https://trusted-cdn.com/library.js"></script>

Custom Blocked Domains

Add your own domains to the blocklist:

window.ZestConfig = {
  mode: 'safe',
  blockedDomains: [
    // Simple domain (defaults to marketing category)
    'custom-tracker.com',

    // With explicit category
    { domain: 'my-analytics.com', category: 'analytics' },
    { domain: 'my-cdn.com', category: 'functional' }
  ]
};

Cookie & Storage Interception

Zest also intercepts cookie and storage operations:

How It Works

1. Intercepts document.cookie setter operations
2. Proxies localStorage.setItem() and sessionStorage.setItem()
3. Categorizes operations based on key name patterns
4. Queues blocked operations
5. Replays when consent is granted

Automatic Categorization

Keys are categorized by matching patterns:

Analytics patterns:

_ga, _gid, _gat, _utm, __utm, plausible, _pk_, matomo, _hj, ajs_

Marketing patterns:

_fbp, _fbc, _gcl, _ttp, ads, doubleclick, __gads, __gpi, _pin_, li_

Functional patterns:

lang, locale, theme, preferences, ui_

Essential patterns (always allowed):

zest_, csrf, xsrf, session, __host-, __secure-

Unknown keys default to the marketing category (strictest).

Custom Patterns

Add your own categorization patterns:

window.ZestConfig = {
  patterns: {
    analytics: [/^my_analytics_/, /^custom_ga/],
    marketing: [/^my_ad_/, /^campaign_/],
    functional: [/^user_pref_/]
  }
};

Script Execution Order

When consent is granted:

1. External scripts are loaded in their original order
2. Inline scripts execute after their dependencies load
3. The zest:consent event fires after all scripts execute

Debugging

Check which scripts were blocked:

// In browser console
document.querySelectorAll('script[type="text/plain"]').forEach(s => {
  console.log('Blocked:', s.src || 'inline script');
});

Best Practices

1. Load Zest first - Before any tracking scripts in your HTML
2. Use safe mode - Good balance of protection and compatibility
3. Tag unknown scripts - Use data-consent-category for scripts Zest doesn't recognize
4. Test thoroughly - Check that your site works after consent is granted
5. Allow essential scripts - Use data-zest-allow for critical third-party libraries